Configure the SDK

Overview

As soon as your app launches, configure the SDK with your API Key. Retrieve your publishable Live key yourself from the Dashboard under Settings → Project API Keys (use the Test key for staging and local development). If your Encore flows include an in-app purchase, you pass a purchase controller to configure() as well. The SDK has no built-in billing: it never runs purchase code you did not write.

Option A: EncoreProvider (recommended)

Wrap your app with EncoreProvider. It calls configure() once, on mount, with your purchase controller bound as part of that call.

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

// Encore decides *when* a purchase happens; your app decides *how*.
const purchaseController: PurchaseController = async ({ productId }) => {
  const outcome = await yourBilling.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_here" purchaseController={purchaseController}>
      <YourApp />
    </EncoreProvider>
  );
}

The provider configures once, so the controller from the first render is the one that is bound. If yours genuinely has to change at runtime, swap it with Encore.setPurchaseController().

If your Encore flows have no in-app purchase, omit the prop. The SDK then never attempts a purchase and every presentation records publisher: 'not_attempted'.

Option B: Configure directly

Outside a React tree, or when you need to configure at a precise point in your startup sequence, call configure() yourself.

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

// At app startup
await Encore.configure('pk_your_api_key_here', { purchaseController });

Return `pending` for deferred purchases

PurchaseResult is three-valued for a reason:

type PurchaseResult = 'purchased' | 'cancelled' | 'pending';

'pending' means the store deferred the purchase: Ask to Buy (parental approval) on iOS, or SCA or a pending Play transaction on Android. The user has neither bought nor abandoned, and the store’s eventual webhook is the source of truth. Returning 'cancelled' for a deferred purchase silently misreports revenue, recording a sale that is still in flight as a decline. Map the deferred branch of your billing library to 'pending'. Throw only for a real failure, which is recorded as publisher: 'failed' with your message. See PurchaseController for RevenueCat, react-native-iap, and custom implementations.

Configuration options

await Encore.configure('pk_your_api_key_here', {
  purchaseController,  // your billing code; omit if your flows have no purchase
  logLevel: 'debug',   // 'none' | 'error' | 'warn' | 'info' | 'debug'
  unlock: 'optimistic' // 'optimistic' | 'strict'
});

Option	Type	Default	Description
`purchaseController`	function	(none)	Your billing code, bound as the SDK’s single purchase path. See PurchaseController
`logLevel`	string	`'none'`	Logging verbosity level
`unlock`	string	`'optimistic'`	How a claim grants access. `'strict'` verifies server-side and persists unverified claims across launches, surfacing late confirmations on `Encore.onOutcome`

Use logLevel: 'debug' during development, then remove it for production builds.

Can’t find your API key? Open your project’s Settings → Project API Keys in the Encore Dashboard and copy the Live key (or Test for non-production builds).

Next Steps

Now that Encore is configured, you’re ready to:

User Management - Identify users for entitlement tracking
Present Offers - Show promotional offers and read the result

iOS

Android

Web

Bridges

Configure the SDK

Overview

Option A: EncoreProvider (recommended)

Option B: Configure directly

Return `pending` for deferred purchases

Configuration options

Next Steps

​Overview

​Option A: EncoreProvider (recommended)

​Option B: Configure directly

​Return pending for deferred purchases

​Configuration options

​Next Steps

Overview

Option A: EncoreProvider (recommended)

Option B: Configure directly

Return `pending` for deferred purchases

Configuration options

Next Steps