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. show() resolves with the complete factual record of what happened. There are no global callbacks to register: control flow lives at the call site.

Present an offer

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

show() never rejects. Every failure, including “nothing was presented”, arrives as a value on the result, so there is no catch block to forget and no silent hang when you do.

Read the result

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 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

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

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} />;
}

Next Steps

Add Subscription Product - 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

Next Steps

​Overview

​Present an offer

​Read the result

​Purchases

​Observe outcomes globally

​Full example

​Next Steps

Overview

Present an offer

Read the result

Purchases

Observe outcomes globally

Full example

Next Steps