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

// Purchase request — delegate to your subscription manager
Encore.onPurchaseRequest(async ({ requestId, productId, placementId }) => {
  try {
    await RevenueCat.purchase(productId);
    await Encore.completePurchaseRequest(requestId, true);
  } catch {
    await Encore.completePurchaseRequest(requestId, false);
  }
});

// Passthrough — user dismissed without purchasing
Encore.onPassthrough(({ placementId }) => {
  // Resume your original flow
});

// Purchase complete (fire-and-forget, for syncing with backends)
Encore.onPurchaseComplete(({ productId, transactionId }) => {
  console.log('Purchase completed:', productId);
});

Each on* method returns an unsubscribe function:

const unsubscribe = Encore.onPassthrough(handler);
// Later:
unsubscribe();

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(requestId, success)

Signal completion of a purchase request initiated via onPurchaseRequest. The native SDK waits for this call before proceeding.

onPurchaseRequest(handler)

Subscribe to purchase request events. Your handler receives { requestId, productId, placementId } and must call completePurchaseRequest when done.

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