Encore React Native SDK

Thin React Native bridge to the native Encore iOS SDK and Encore Android SDK. Presents retention offers with native UI and delegates purchases to your existing subscription manager.

Installation

npm install @encorekit/react-native

iOS

cd ios && pod install

Android

No additional setup required — com.encorekit:encore resolves from Maven Central, which is included by default in Android projects. The React Native module auto-links with RN 0.60+.

Quick Start

1. Wrap Your App with EncoreProvider

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

export default function App() {
  return (
    <EncoreProvider apiKey="your_api_key" options={{ logLevel: 'debug' }}>
      <YourApp />
    </EncoreProvider>
  );
}

The provider calls configure and registerCallbacks once on mount.

2. Identify Users

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

// After authentication
Encore.identify('user_123', {
  email: '[email protected]',
  subscriptionTier: 'premium',
});

// On logout
Encore.reset();

3. Show a Placement

const result = await Encore.show('paywall');
// result.status: 'granted' | 'not_granted' | 'completed' | 'dismissed' | 'no_offers'

4. Handle Callbacks

Setter semantics. onPurchaseRequest, onPurchaseComplete, and onPassthrough each replace the previous handler when called again (matching iOS, Android, and Flutter). They are global singleton handlers, not multi-listener subscriptions. No manual cleanup is required — re-registration is safe and idempotent.

// Register once, e.g. right after configure or at app startup
Encore.onPurchaseRequest(async ({ productId, placementId }) => {
  try {
    await RevenueCat.purchase(productId);
    await Encore.completePurchaseRequest(true);
  } catch {
    await Encore.completePurchaseRequest(false);
  }
});

Encore.onPurchaseComplete(({ productId, transactionId }) => {
  // Optional: sync with backends that don't auto-detect StoreKit/Play Billing
});

Encore.onPassthrough(({ placementId }) => {
  // User dismissed without purchasing — resume your original flow
});

API Reference

configure(apiKey, options?)

Initialize the SDK. Called automatically by EncoreProvider.

| Parameter | Type | Description | |:----------|:-----|:------------| | apiKey | string | Your Encore API key | | options.logLevel | 'none' \| 'error' \| 'warn' \| 'info' \| 'debug' | Log verbosity (default: 'none') |

identify(userId, attributes?)

Associate a user ID with SDK events.

setUserAttributes(attributes)

Merge attributes into the current user profile.

reset()

Clear user data and generate a new anonymous ID. Call on logout.

show(placementId)

Present a native offer sheet. Returns PlacementResult.

registerCallbacks()

Register native event handlers (purchase request, purchase complete, passthrough). Called automatically by EncoreProvider.

completePurchaseRequest(success)

Signal completion of a purchase request initiated via onPurchaseRequest. Pass true on successful purchase, false on failure/cancellation.

onPurchaseRequest(handler)

Register a handler for purchase request events (setter semantics — replaces any previous handler). Your handler receives { productId, placementId?, promoOfferId? } and should call completePurchaseRequest when done. Returns an unsubscribe function.

onPurchaseComplete(handler)

Subscribe to purchase completion events. Receives { productId, transactionId }.

onPassthrough(handler)

Subscribe to passthrough events (user dismissed without purchasing). Receives { placementId }.

EncoreProvider

React context provider. Props:

| Prop | Type | Description | |:-----|:-----|:------------| | apiKey | string | Your Encore API key | | options | ConfigureOptions | Optional configuration |

useEncoreContext()

Hook returning the full EncoreSDK interface. Must be used within EncoreProvider.

Types

interface UserAttributes {
  email?: string;
  firstName?: string;
  lastName?: string;
  phoneNumber?: string;
  postalCode?: string;
  city?: string;
  state?: string;
  countryCode?: string;
  latitude?: string;
  longitude?: string;
  dateOfBirth?: string;
  gender?: string;
  language?: string;
  subscriptionTier?: string;
  monthsSubscribed?: string;
  billingCycle?: string;
  lastPaymentAmount?: string;
  lastActiveDate?: string;
  totalSessions?: string;
  custom?: Record<string, string>;
}

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

Requirements

• React Native 0.60+
• iOS 15.0+
• Android API 21+
• Node 16+

Note on Entitlements

Entitlement tracking is handled by the native SDKs and your subscription manager. The React Native bridge does not expose entitlement query methods directly — use your subscription manager's React Native SDK (RevenueCat, Adapty, etc.) for entitlement checks.

License

MIT