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

show() resolves with the complete factual record of what happened, and it never rejects. Every failure, including “nothing was presented”, arrives as a value on the result, so there is no catch block to forget:

Reward Users
Reduce Churn

import Encore, { UseCase } from '@encorekit/react-native';

async function onStreakKept() {
  const result = await Encore.placement('streak_day_7')
    .useCase(UseCase.rewardUsers)
    .headline('Nice work, Sam!')   // optional; falls back to the copy resolved for your app
    .show();

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

Select UseCase.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.

async function onCancelTapped() {
  const result = await Encore.placement('cancel_flow').show();

  if (result.status === 'presented' && (result.claim !== null || result.publisher === 'purchased')) {
    // The user claimed an offer or completed your purchase.
    navigation.navigate('Home');
  } 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() · PresentationResult.

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

Read the result

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

Field	What it reports
`advertiser`	Encore’s funnel: `not_attempted`, `claimed`, `verified`, `cooldown`, or `failed`
`publisher`	Your funnel: what your purchase controller returned
`dismissal`	How the sheet went away
`claim`	Shorthand for the offer behind a `claimed` or `verified` advertiser outcome, else `null`

A single presentation can claim an offer and run a purchase, so the two funnels are recorded side by side rather than competing for one winning value.

There is deliberately no unlocked boolean. What a claim means is a property of the variant flow that served it, so an SDK-computed verdict could contradict the flow that actually ran. Branch on the raw axes, as above. See PresentationResult.

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 purchase controller. Pass it to configure(); see Configure the SDK.

const purchaseController: PurchaseController = async ({ productId }) => {
  const outcome = await yourBilling.purchase(productId);
  if (outcome.userCancelled) return 'cancelled';
  if (outcome.deferred) return 'pending';
  return 'purchased';
};

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, subscribe to the outcomes stream. It appends rather than replacing, so several observers can listen at once.

useEffect(
  () =>
    Encore.onOutcome((outcome) => {
      if (outcome.type === 'presentation') {
        analytics.track('encore_presentation', outcome.result);
      } else {
        refreshEntitlements();   // strict_unlock_verified
      }
    }),
  [],
);

There is no replay, so subscribe at startup. See onOutcome().

Full example: cancel flow

import { useEffect } from 'react';
import Encore, { EncoreProvider } from '@encorekit/react-native';
import type { PurchaseController } from '@encorekit/react-native';

const purchaseController: PurchaseController = async ({ productId }) => {
  const outcome = await billingService.purchase(productId);
  if (outcome.userCancelled) return 'cancelled';
  if (outcome.deferred) return 'pending';
  return 'purchased';
};

export default function App() {
  return (
    <EncoreProvider apiKey="pk_your_api_key" purchaseController={purchaseController}>
      <MainApp />
    </EncoreProvider>
  );
}

function SubscriptionScreen() {
  useEffect(
    () => Encore.onOutcome((outcome) => analytics.track('encore_outcome', outcome)),
    [],
  );

  const handleCancel = async () => {
    const result = await Encore.placement('cancel_flow').show();

    if (result.status === 'presented' && (result.claim !== null || result.publisher === 'purchased')) {
      showRetentionConfirmation();
    } else {
      await proceedWithCancellation();
    }
  };

  return <Button title="Cancel Subscription" onPress={handleCancel} />;
}

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: set up the store subscriptions your controller purchases
Integration Patterns - Where to put the call site, the controller, and the stream
SDK Reference - Complete API documentation

iOS

Android

Web

Bridges

Presenting Offers

Overview

Present an offer

Read the result

Purchases

Observe outcomes globally

Full example: cancel flow

Bring users back to finish their gift

Next Steps

​Overview

​Present an offer

​Read the result

​Purchases

​Observe outcomes globally

​Full example: cancel flow

​Bring users back to finish their gift

​Next Steps

Overview

Present an offer

Read the result

Purchases

Observe outcomes globally

Full example: cancel flow

Bring users back to finish their gift

Next Steps