Presenting Offers

Overview

Encore presents a premium brand offer (a real perk a brand funds to acquire customers, such as a free trial, discount, or credit) at a moment you choose. Start with Reward Users: a reward sheet at a moment the user just earned, such as a completed purchase, a streak, or a milestone, at no cost to you. The other use case, Reduce Churn, presents offers in a cancel flow or after a paywall decline.

Present an offer

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() never throws. Every failure, including “nothing was presented”, is a value on the returned EncorePresentationResult:

Reward Users
Reduce Churn

import 'package:encore_flutter/encore_flutter.dart';

Future<void> onStreakKept() async {
  final result = await Encore.placement('streak_day_7')
      .useCase(EncoreUseCase.rewardUsers)
      .headline('Nice work, Sam!')   // optional; falls back to the copy resolved for your app
      .show();

  final claim = result.claim;
  if (claim != null) {
    // The user claimed an offer. Keep claim.transactionId; it carries the attribution.
    final transactionId = claim.transactionId;
    if (transactionId != null) persistClaim(transactionId);
  }
  // Every other result: carry on with your own celebration screen.
}

Select EncoreUseCase.rewardUsers on every reward placement. A reward placement never runs a purchase and never falls back to the paywall sheet, so it needs no subscription product and no purchase controller. The walkthrough, including per-call copy, is the Reward Placements guide.

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

  final converted = result.claim != null ||
      result.publisher == EncorePublisherOutcome.purchased;
  if (converted) {
    // The user claimed an offer or completed your purchase.
    grantAccess();
  } else {
    // Dismissed, declined, no offers, control cohort, or an error.
    await proceedWithCancellation();
  }
}

A placement that omits useCase() is a Reduce Churn placement. Never block the user’s original action: when the result shows no claim and no purchase, run your original flow.

Contracts: placement() · EncorePresentationResult.

result.claim means the user tapped through to an offer, not that they finished it.

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; credit the user once per transactionId. 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

This section applies to Reduce Churn placements only. A reward placement never runs a purchase, so an app that presents only reward placements can skip it. 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.refresh(transactionId);
  }
});

There is no replay, so subscribe at startup.

Full example: cancel flow

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'),
        ),
      ),
    );
  }
}

Bring users back to finish their gift

Put a Claim Reminder on your home tab. It stays hidden until the user claims a gift, then reminds them to finish. Once they do, it thanks them or steps aside. Encore manages that. You can also put a Gifts Button on your reward screen, so users can open their gifts there whenever offers are waiting. Both need version 2.4.0 or later of the SDK. See the trigger components quickstart.

Next Steps

Reward Placements: reward a user at a moment they just earned, with copy you set per call
Add Subscription Product: Reduce Churn only. 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

Read the result

When nothing was presented

Purchases

Observe outcomes globally

Full example: cancel flow

Bring users back to finish their gift

Next Steps

​Overview

​Present an offer

​Read the result

​When nothing was presented

​Purchases

​Observe outcomes globally

​Full example: cancel flow

​Bring users back to finish their gift

​Next Steps

Overview

Present an offer

Read the result

When nothing was presented

Purchases

Observe outcomes globally

Full example: cancel flow

Bring users back to finish their gift

Next Steps