Presenting Offers

Overview

Encore allows you to present targeted offers to users in exchange for rewards (free trials, discounts, credits) at critical moments like cancellation flows or feature paywalls. The native SDK renders all offer UI natively (SwiftUI on iOS, Jetpack Compose on Android) — the Flutter layer triggers presentation and receives results.

Present Offers

Presenting an Encore offer is a single call:

ElevatedButton(
  onPressed: () {
    Encore.placement('cancellation_flow').show();
  },
  child: const Text('Cancel Subscription'),
)

Handle Offer Results

Choosing your integration shape: This page shows the handler pattern. If your call site has direct access to purchase logic, the async-result pattern is often cleaner. See Integration Patterns for the decision tree and Flutter Integration Patterns for Dart examples.

Register handlers that tell the SDK how to complete purchases and what to do when a user dismisses. Register these once after configure().

Register `onPurchaseRequest`

Called when a user accepts an offer and a purchase is needed. Use this to trigger a purchase via your Flutter-side subscription manager (RevenueCat, in_app_purchase, etc.).

Encore.shared.onPurchaseRequest((purchaseRequest) async {
  // Example using RevenueCat Flutter SDK
  final products = await Purchases.getProducts([purchaseRequest.productId]);
  if (products.isNotEmpty) {
    await Purchases.purchaseStoreProduct(products.first);
  }
});

If you do not set onPurchaseRequest, the native SDK handles the purchase itself using StoreKit (iOS) or Play Billing (Android) and presents the native subscription modal automatically. This is useful for apps that don’t use a third-party subscription manager.

Register `onPassthrough`

Called when the user dismisses the offer or no offers are available. Use this to resume the user’s original action (e.g., proceed with cancellation).

Encore.shared.onPassthrough((placementId) {
  // Resume your original user flow
  navigator.proceedWithCancellation();
});

`onPurchaseComplete` (Optional)

Only fires when no onPurchaseRequest handler is set and the native SDK handles the purchase itself. Use this to sync the transaction with subscription managers that don’t auto-detect native purchases.

Encore.shared.onPurchaseComplete((result, productId) {
  debugPrint('Native purchase completed: $productId');
});

Summary

Callback	When it fires	Required?
`onPurchaseRequest`	User accepts an offer, purchase needed	Recommended
`onPassthrough`	User dismisses or no offers available	Yes
`onPurchaseComplete`	Native purchase finishes (no `onPurchaseRequest` set)	Optional

onPassthrough should be registered before presenting any placements so users are never blocked from completing their intended action.

Using the Result

placement().show() returns an EncorePresentationResult that you can use for flow control:

final result = await Encore.placement('cancel_flow').show();

switch (result) {
  case EncorePresentationResultGranted(:final offerId):
    debugPrint('Offer granted: $offerId');
  case EncorePresentationResultNotGranted(:final reason):
    debugPrint('Not granted: $reason');
}

Full Example

import 'package:flutter/material.dart';
import 'package:encore_flutter/encore_flutter.dart';

class CancelScreen extends StatelessWidget {
  const CancelScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Account')),
      body: Center(
        child: FilledButton(
          onPressed: () async {
            final result = await Encore.shared
                .placement('cancellation_flow')
                .show();

            if (result is EncorePresentationResultGranted) {
              ScaffoldMessenger.of(context).showSnackBar(
                const SnackBar(content: Text('Offer applied!')),
              );
            }
          },
          child: const Text('Cancel Subscription'),
        ),
      ),
    );
  }
}

Next Steps

Add Subscription Product — Create a subscription product and connect it to Encore

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

Integration Patterns

Automated Messaging

Offer Catalog

Offers API

Overview

Present Offers

Handle Offer Results

Register `onPurchaseRequest`

Register `onPassthrough`

`onPurchaseComplete` (Optional)

Summary

Using the Result

Full Example

Next Steps

​Overview

​Present Offers

​Handle Offer Results

​Register onPurchaseRequest

​Register onPassthrough

​onPurchaseComplete (Optional)

​Summary

​Using the Result

​Full Example

​Next Steps

Overview

Present Offers

Handle Offer Results

Register `onPurchaseRequest`

Register `onPassthrough`

`onPurchaseComplete` (Optional)

Summary

Using the Result

Full Example

Next Steps