Presenting Offers

Overview

Encore lets you present a premium brand offer (a real perk a brand funds to acquire customers, such as a free trial, discount, or credit) 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 the result. show() completes with the complete factual record of what happened. There are no global handlers to register: control flow lives at the call site.

Present an offer

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

show() never throws. Every failure, including “nothing was presented”, is a value on the returned EncorePresentationResult.

Select a use case

useCase() selects which Encore surface the placement presents. It defaults to EncoreUseCase.reduceChurn, so an existing integration that never calls it is unaffected.

await Encore.placement('milestone_reached')
    .useCase(EncoreUseCase.rewardUsers)
    .headline("That's three days in a row staying informed 🔥")
    .subheadline("Here's a little thank you from us")
    .show();

Case	Wire value	Surface
`EncoreUseCase.reduceChurn`	`churn-intervention`	Second-chance monetization after a paywall decline. The default
`EncoreUseCase.rewardUsers`	`post-action-reward`	A brand-funded reward at a moment the user just accomplished something. Claim-only; never presents IAP

The identifiers name the capability; nativeValue carries the sdui_use_case label the backend stores. The two are pinned explicitly rather than derived from each other, so renaming a case can never silently change what goes over the wire. Pass the case, not a string built from its name.

A use case with no enabled variant resolves EncoreNotPresented(useCaseUnavailable) rather than falling back to the churn-intervention sheet: an in-app-purchase screen at a moment the user was meant to be rewarded is worse than presenting nothing. See Reward Users.

Copy overrides

headline() and subheadline() override the sheet’s copy for one presentation, on every use case. The native side writes the value into the variable the active template reads. Priority order, first one set wins: this value, then the copy Encore resolved for your app, then the shipped template default. A blank string is ignored, so the chain falls through rather than rendering an empty line. You pass the finished string, so localization, pluralization, wording, and emoji stay yours. See Where the copy comes from.

Read the result

EncorePresentationResult is a sealed pair, so Dart 3 gives you an exhaustive switch:

switch (result) {
  case EncoreNotPresented(:final reason):
    // Nothing appeared. Continue the user's original action.
    proceedWithCancellation(reason);
  case EncorePresented(:final outcome):
    final converted = outcome.advertiser is EncoreAdvertiserClaimed ||
        outcome.advertiser is EncoreAdvertiserVerified ||
        outcome.publisher == EncorePublisherOutcome.purchased;
    converted ? grantAccess() : proceedWithCancellation(outcome.dismissal);
}

Fact readers give you one axis at a time when you don’t want to pattern-match the whole record:

final converted = result.claim != null ||
    result.publisher == EncorePublisherOutcome.purchased;

A presented record carries two independent funnels plus how the sheet went away:

Field	What it reports
`advertiser`	Encore’s funnel: `EncoreAdvertiserNotAttempted`, `Claimed`, `Verified`, `Cooldown`, or `Failed`
`publisher`	Your funnel: what your purchase controller reported
`dismissal`	How the sheet went away
`claim`	The claimed offer behind a `Claimed` or `Verified` advertiser outcome, else `null`

One presentation can claim an offer and run a purchase, so both are recorded rather than competing for one winning case. notAttempted is a real value, meaning “the funnel was open and nothing entered it”, never null. claim carries the offer itself:

class EncoreClaimedOffer {
  /// The claimed offer. Null on Android, whose claim record carries only the
  /// campaign; on iOS an offer *is* a campaign, so this equals [campaignId].
  final String? offerId;

  final String campaignId;

  /// The brand behind the offer.
  final String advertiserName;

  /// Joins this claim to a later [EncoreStrictUnlockVerified] outcome, and to
  /// the server-side completion event that can land days afterwards. Nullable:
  /// the transaction write can fail while the claim still happened.
  final String? transactionId;
}

transactionId is the one to hold on to. The brand-side completion lands later, sometimes days later, and reaches your server through the offer-completed webhook, which carries the same value and treats it as the idempotency key. It is the only way to match the result your app just received against the completion it eventually produces.

There is deliberately no SDK-computed “unlocked” verdict. What a claim means is a property of the variant flow that served it, so any projection over app-global config can contradict the flow that actually ran. Branch on the raw axes.

When nothing was presented

EncoreNotPresented is not a synonym for failure:

Reason	Meaning
`noOffers`	No offers matched this user. Don’t retry immediately
`experimentControl`	Control cohort: exposure logged, no UI by design
`useCaseUnavailable`	The requested use case resolved no layout for this app
`alreadyPresenting`	A presentation is already on screen
`noForegroundActivity`	Android only: no foreground Activity was available
`unsupportedOS`	iOS only: the device is below the SDK’s minimum OS version
`iapFirstDeclined`	Android only: an IAP-first layout ran its purchase before any UI and the user declined
`error`	A network, decoding, or integration failure. Read `errorType` and `errorMessage`
`notConfigured`	A method was called before `configure()`

Run your fallback for all of them, and log only the error case.

Purchases

A user who accepts an offer that carries an in-app purchase triggers your registered EncorePurchaseController. It is registered at configure; see Configure the SDK.

class AppPurchases implements EncorePurchaseController {
  @override
  Future<EncorePurchaseResult> purchase(EncorePurchaseRequest request) async {
    try {
      await mySubscriptionManager.purchase(request.productId);
      return EncorePurchaseResult.purchased;
    } on UserCancelled {
      return EncorePurchaseResult.cancelled;
    } on PurchaseDeferred {
      return EncorePurchaseResult.pending;
    }
  }
}

Return pending for deferred purchases. Ask to Buy on iOS, or SCA or a pending Play transaction on Android, means the user has neither bought nor abandoned; the store’s webhook settles it later. Returning cancelled for these silently misreports revenue, recording a live sale as a decline.

Observe outcomes globally

For analytics forwarding, app-owned state, or a debug overlay, listen to the outcomes stream. It is multicast, so several listeners can subscribe at once.

Encore.shared.outcomes.listen((outcome) {
  switch (outcome) {
    case EncorePlacementPresentation(:final placementId, :final result):
      analytics.log('encore_presentation', placementId, result);
    case EncoreStrictUnlockVerified(:final transactionId):
      // A strict claim the server confirmed after its flow ended, possibly on
      // a later launch. Entitlements are already refreshed natively.
      entitlements.refresh(transactionId);
  }
});

There is no replay, so subscribe at startup.

Full Example

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

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

  Future<void> _onCancel(BuildContext context) async {
    final result = await Encore.placement('cancel_flow').show();

    final converted = result.claim != null ||
        result.publisher == EncorePublisherOutcome.purchased;

    if (!context.mounted) return;
    if (converted) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Offer applied!')),
      );
    } else {
      await proceedWithCancellation();
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Account')),
      body: Center(
        child: FilledButton(
          onPressed: () => _onCancel(context),
          child: const Text('Cancel Subscription'),
        ),
      ),
    );
  }
}

Next Steps

Add Subscription Product: create a subscription product and connect it to Encore
Integration Patterns: where the controller, the call site, and the stream each belong

iOS

Android

Web

Bridges

Presenting Offers

Overview

Present an offer

Select a use case

Copy overrides

Read the result

When nothing was presented

Purchases

Observe outcomes globally

Full Example

Next Steps

​Overview

​Present an offer

​Select a use case

​Copy overrides

​Read the result

​When nothing was presented

​Purchases

​Observe outcomes globally

​Full Example

​Next Steps

Overview

Present an offer

Select a use case

Copy overrides

Read the result

When nothing was presented

Purchases

Observe outcomes globally

Full Example

Next Steps