React Native Integration Patterns

Overview

Encore.placement(id).show() returns a Promise<PlacementResult>. You can either await it and branch on the returned value (async-result) or register global onPurchaseRequest / onPassthrough handlers (handler-based). Both work; pick whichever fits the call site. For the cross-platform decision tree, see Integration Patterns.

Async-result pattern

Use this when the component that triggers show() already has access to your purchase + decline logic.

Basic example

import Encore from '@tryencorekit/react-native';

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

  switch (result.status) {
    case 'granted':
    case 'completed':
      // User accepted
      navigation.navigate('Home');
      break;
    case 'not_granted':
    case 'dismissed':
    case 'no_offers':
      // User declined or no offers — proceed with original flow
      await proceedWithCancellation(result.reason);
      break;
  }

  // Code that runs in both branches lives here, written once
  analytics.track('cancel_flow_resolved');
}

From a component

function CancelScreen() {
  const handleCancel = async () => {
    const result = await Encore.placement('cancel_flow').show();
    if (result.status === 'granted' || result.status === 'completed') {
      navigation.navigate('Home');
    } else {
      await proceedWithCancellation(result.reason);
    }
  };

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

Result type

interface PlacementResult {
  status: 'granted' | 'not_granted' | 'completed' | 'dismissed' | 'no_offers';
  reason?: string;
  entitlement?: string;
  offerId?: string;
  campaignId?: string;
}

iOS surfaces granted / not_granted; Android surfaces completed / dismissed / no_offers. Treat both grant cases (granted, completed) as success and the rest as decline. See PlacementResult.

Handler pattern

Use this when show() is invoked from many sites that share post-purchase logic, or when the trigger is far from your billing code.

Register at app startup

import { useEffect } from 'react';
import Encore, { EncoreProvider } from '@tryencorekit/react-native';

export default function App() {
  return (
    <EncoreProvider apiKey="pk_live_...">
      <RootHandlers />
      <MainNavigator />
    </EncoreProvider>
  );
}

function RootHandlers() {
  useEffect(() => {
    const unsubPurchase = Encore.onPurchaseRequest(async ({ productId }) => {
      try {
        await billing.purchase(productId);
        await Encore.completePurchaseRequest(true);
      } catch {
        await Encore.completePurchaseRequest(false);
      }
    });

    const unsubPassthrough = Encore.onPassthrough(({ placementId }) => {
      AppRouter.handlePassthrough(placementId);
    });

    return () => {
      unsubPurchase();
      unsubPassthrough();
    };
  }, []);

  return null;
}

You must call Encore.completePurchaseRequest(success) in every code path of onPurchaseRequest. Failing to do so blocks the SDK from presenting future offers. See completePurchaseRequest().

Then `show()` from anywhere

<Button title="Cancel Subscription" onPress={() => Encore.placement('cancel_flow').show()} />

When to use which

Async-result — component already imports your billing client. Branch-specific code lives at the call site.
Handler — registered once at app root; many show() sites share the same purchase delegation.
Mixed — register handlers for cross-cutting telemetry; still await show() for site-specific UI navigation.

See the decision tree for the full rationale.

Re-registration semantics

const unsub1 = Encore.onPurchaseRequest(handlerV1);
const unsub2 = Encore.onPurchaseRequest(handlerV2); // replaces handlerV1

Internally, each setter calls currentSubscription?.remove() before adding the new listener — there is no double-fire. The returned unsubscribe function is useful for component lifecycles (call from a useEffect cleanup) but is not required to prevent double-fires when you replace via re-registration.

Platform-specific notes

Status values vary by platform — iOS surfaces granted / not_granted; Android surfaces completed / dismissed / no_offers. Code that handles both cases is portable.
Event-emitter under the hood — handlers are wired via NativeEventEmitter, but the JS API has replace semantics on the JS side as well. You don’t need to manually remove listeners between re-registrations.
completePurchaseRequest is required — unlike iOS / Android native SDKs where onPurchaseRequest simply throws or returns, RN’s bridge needs an explicit ack. Always call it.
Provider — wrap your root in <EncoreProvider apiKey="..."> so the bridge is configured before any show() call.

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

Integration Patterns

Automated Messaging

Offer Catalog

Offers API

React Native Integration Patterns

Overview

Async-result pattern

Basic example

From a component

Result type

Handler pattern

Register at app startup

Then `show()` from anywhere

When to use which

Re-registration semantics

Platform-specific notes

See also

​Overview

​Async-result pattern

​Basic example

​From a component

​Result type

​Handler pattern

​Register at app startup

​Then show() from anywhere

​When to use which

​Re-registration semantics

​Platform-specific notes

​See also

Overview

Async-result pattern

Basic example

From a component

Result type

Handler pattern

Register at app startup

Then `show()` from anywhere

When to use which

Re-registration semantics

Platform-specific notes

See also