Updating to 2.x

​

Overview

• Purchases run through a purchase controller you pass to configure(). An async function returning 'purchased' | 'cancelled' | 'pending'. The SDK never runs purchase code you didn’t write.
• show() never rejects. Errors arrive as values on the result.
• The result is a factual record, not a single verdict: two independent funnels plus how the sheet ended.
• Global on* setters are retired. Control flow lives at the call site; passive observation moves to the Encore.onOutcome stream.

​

Step 1: Update the package

npm install @encorekit/react-native@^2.0.0

yarn add @encorekit/react-native@^2.0.0

cd ios && pod install --repo-update && cd ..

​

Step 2: Move purchases to a purchase controller

Encore.onPurchaseRequest(async ({ productId }) => {
  try {
    await Purchases.purchaseProduct(productId);
    await Encore.completePurchaseRequest(true);
  } catch {
    await Encore.completePurchaseRequest(false);
  }
});

import type { PurchaseController } from '@encorekit/react-native';

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

<EncoreProvider apiKey="pk_..." purchaseController={purchaseController}>
  <YourApp />
</EncoreProvider>

// or, outside React:
await Encore.configure('pk_...', { purchaseController });

1. The answer is a return value, not a second call. The bridge correlates each request by id internally, so a late reply can no longer land on a live flow. Nothing is left to forget, and the SDK can no longer be wedged by a missing acknowledgement.
2. The result is three-valued. See pending is not a failure below, which is the whole reason the 1.x pair was removed rather than shimmed.
3. Throwing is meaningful. A thrown error records publisher: 'failed' with your message, and the flow continues. Map your billing layer’s “user cancelled” error to 'cancelled' rather than letting it throw.

​

pending is not a failure

​

Where the controller goes

​

Step 3: Update show() call sites

// 1.x
try {
  const result = await Encore.placement('cancel_flow').show();
  if (result.status === 'granted') unlock();
  else runOriginalFlow();
} catch {
  runOriginalFlow();   // often forgotten, causing a silent hang
}

// 2.0
const result = await Encore.placement('cancel_flow').show();
if (result.status === 'presented' && (result.claim !== null || result.publisher === 'purchased')) {
  unlock();
} else {
  runOriginalFlow();
}

​

Step 4: Update result handling

if (result.status === 'granted') grantAccess();

if (result.status === 'presented') {
  const converted = result.claim !== null || result.publisher === 'purchased';
  if (converted) grantAccess();
}

​

Step 5: Replace global callbacks with the outcomes stream

const result = await Encore.placement('cancel_flow').show();
const passedThrough =
  result.status !== 'presented' ||
  (result.claim === null && result.publisher !== 'purchased');

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

• It appends. The 1.x setters replaced the previous handler; this is a real subscription, and several observers can listen at once, matching the multicast streams both natives expose.
• There is no replay. Subscribe at startup, or you miss outcomes emitted before you subscribed.

​

Removed APIs at a glance

​

Behavior changes to be aware of

• Errors no longer reject. Old catch fallback blocks are dead code; run fallback off not_presented instead.
• Claim-then-purchase records both funnels. 1.x collapsed the flow to a single winner. 2.0 carries advertiser: { type: 'claimed', … } and publisher: 'purchased' side by side, and the result resolves once, after the purchase settles.
• A deferred purchase is now visible. Flows that previously recorded a failure for Ask to Buy or SCA now record publisher: 'pending', provided your controller returns 'pending' for them.
• useCase, headline and subheadline now actually work. The JS builder already exposed them in 1.x, but the bridge had no native method behind them, so the values were dropped with a warning and rewardUsers could never present. Both bridges now forward all three on every show().
• reset() does not clear the controller. It is build-time wiring, not user state, so logging a user out does not require re-registering.

​

New in 2.0

• The outcomes stream, including late strict_unlock_verified events that survive process death.
• Unlock mode. options.unlock: 'strict' verifies claims server-side, persisting unverified claims and re-checking them across launches. 'optimistic' (the default, and 1.x’s behavior) records the claim and finishes.
• A working reward surface. .useCase(UseCase.rewardUsers) presents the claim-only reward sheet instead of the churn-intervention sheet, with .headline() / .subheadline() copy overrides.
• basePlanId on the purchase request, naming the Google Play base plan to select when a product exposes several.

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

​

Verify the migration

1. npx tsc --noEmit is clean, with no references to removed 1.x APIs.
2. If your Encore flows include an in-app purchase, a purchase controller is passed to configure(), either directly or as the EncoreProvider prop.
3. Your controller returns 'pending' for deferred purchases, and 'cancelled' only for a genuine user cancellation.
4. Every fallback path runs off the no-claim, no-purchase branch, not a catch block.
5. Test the full flow on a device on both platforms: present a placement, claim an offer, complete a purchase, and dismiss without acting. Each path should resolve exactly once with the result you expect.