React Native SDK

Helium supports two SDK packages depending on your setup:

	Package	Platforms
Expo 52+	expo-helium	iOS + Android
Older Expo / Bare	@tryheliumai/paywall-sdk-react-native	iOS only

We support Expo 49+ but recommend Expo 53+.

---

1. Install the SDK

Expo 52+

npx expo install expo-helium

npm install @tryheliumai/paywall-sdk-react-native
# or
yarn add @tryheliumai/paywall-sdk-react-native

# Bare only — install native dependencies
npx react-native link @tryheliumai/paywall-sdk-react-native

Expo users: Helium uses native code, so you must use a development build. Expo Go will not work.

npx expo run:ios   # or npx expo run:ios --device

---

2. Initialize Helium

Call initialize early in your app’s lifecycle, typically in your root component. Your API key is available in the Helium dashboard → Profile.

Expo 52+

import { initialize } from 'expo-helium';

function App() {
  useEffect(() => {
    void initialize({ apiKey: 'YOUR_API_KEY' });
  }, []);
}

import { initialize } from '@tryheliumai/paywall-sdk-react-native';

function App() {
  useEffect(() => {
    void initialize({ apiKey: 'YOUR_API_KEY' });
  }, []);
}

---

3. Show a Paywall

Before calling presentUpsell, make sure you have a trigger and workflow configured in the Helium dashboard.

Expo 52+

import { presentUpsell } from 'expo-helium';

function YourComponent() {
  return (
    <Button
      title="Try Premium"
      onPress={() => presentUpsell({ triggerName: 'premium_feature_press' })}
    />
  );
}

import { presentUpsell } from '@tryheliumai/paywall-sdk-react-native';

function YourComponent() {
  return (
    <Button
      title="Try Premium"
      onPress={() => presentUpsell({ triggerName: 'premium_feature_press' })}
    />
  );
}

PresentUpsellParams · type

Show Properties

triggerName · string · required

The trigger name configured in the Helium dashboard.

eventHandlers · PaywallEventHandlers?

(Optional) Handlers for open, close, dismiss, purchase, open-fail, and custom action events.

customPaywallTraits · Record<string, any>?

(Optional) Custom key/value pairs passed to the paywall.

dontShowIfAlreadyEntitled · boolean? · default: false

(Optional) If true, skips the paywall when the user already has an entitlement for a product in it.

onEntitled · (() => void)?

(Optional) Called on purchase success or restore. Also called instead of showing the paywall when dontShowIfAlreadyEntitled is true and the user is already entitled.

onPaywallUnavailable · (() => void)?

(Optional) Called if both the desired paywall and its fallback fail to show. Uncommon, but worth handling. See Fallback Paywalls.

---

Recommended Setup

The following steps are optional but strongly recommended for production apps.

Identify Users

User identification is optional. It improves targeting accuracy and event attribution in external analytics. Set user identity during initialize for consistency from the first session.

Set during initialize

await initialize({
  apiKey: 'YOUR_API_KEY',
  customUserId: 'your-user-id',
  customUserTraits: {
    hasOnboarded: true,
    plan: 'free',
  },
});

import { setCustomUserId } from 'expo-helium';

setCustomUserId('your-user-id');

---

Paywall Events

Helium emits events throughout the paywall lifecycle. You can handle them per-presentation or globally.

Per-presentation handlers

Pass eventHandlers to presentUpsell:

presentUpsell({
  triggerName: 'my_paywall',
  eventHandlers: {
    onOpen: (event) => console.log('Opened:', event.type),
    onClose: (event) => console.log('Closed:', event.type),
    onDismissed: (event) => console.log('Dismissed:', event.type),
    onPurchaseSucceeded: (event) => console.log('Purchased:', event.type),
    onOpenFailed: (event) => console.log('Open failed:', event.type),
    onCustomPaywallAction: (event) => console.log('Custom action:', event.type),
    onAnyEvent: (event) => {
      // Fires for all of the above.
      // Note: specific handlers (e.g. onOpen) and onAnyEvent both fire for the same event.
    },
  },
});

Global event listener

Pass onHeliumPaywallEvent to initialize to handle events across all paywalls without passing handlers at each call site:

await initialize({
  apiKey: 'YOUR_API_KEY',
  onHeliumPaywallEvent: (event) => {
    switch (event.type) {
      case 'paywallOpen':
        break;
      case 'purchaseSucceeded':
        // Handle successful purchase
        break;
    }
  },
});

You can also forward all events to an existing analytics provider.

---

Fallback Paywalls

Set up fallbacks to handle the rare case where a paywall fails to load. This is strongly recommended before going to production.

Follow the fallback bundle guide once you have a production paywall ready.

---

Checking Entitlements

Check entitlement status before showing a paywall to avoid showing it to users who are already subscribed.

Using dontShowIfAlreadyEntitled

presentUpsell({
  triggerName: 'my_paywall',
  dontShowIfAlreadyEntitled: true,
  onEntitled: () => {
    // User is already entitled or just completed a purchase
  },
});

const hasActiveSubscription = await hasAnyActiveSubscription();

if (hasActiveSubscription) {
  // Grant access to premium content
} else {
  presentUpsell({
    triggerName: 'my_paywall',
    eventHandlers: {
      onPurchaseSucceeded: (event: PurchaseSucceededEvent) => {
        // Grant access to premium content
      },
    },
  });
}

All Entitlement Methods

Method	Returns	Description
hasAnyActiveSubscription()	Promise<boolean>	Returns true if the user has any active subscription (including non-renewable).
hasAnyEntitlement()	Promise<boolean>	Returns true if the user has any entitlement.
hasEntitlementForPaywall(trigger)	Promise<boolean | undefined>	Returns true if the user is entitled to any product in a specific paywall. Returns undefined if the paywall hasn’t loaded yet.

---

Advanced

RevenueCat Integration

By default, Helium manages purchases directly. If you’re already using RevenueCat, pass createRevenueCatPurchaseConfig to initialize to keep RevenueCat in control.

Make sure RevenueCat is installed (Expo · React Native) and initialized via Purchases.configure() before calling Helium.initialize.

Expo 52+

import { initialize } from 'expo-helium';
import { createRevenueCatPurchaseConfig } from 'expo-helium/src/revenuecat';

await initialize({
  apiKey: 'YOUR_API_KEY',
  purchaseConfig: createRevenueCatPurchaseConfig(),
  revenueCatAppUserId: await Purchases.getAppUserID(),
});

import { initialize } from '@tryheliumai/paywall-sdk-react-native';
import { createRevenueCatPurchaseConfig } from '@tryheliumai/paywall-sdk-react-native/src/revenuecat';

// Option A: let Helium initialize RevenueCat
await initialize({
  apiKey: 'YOUR_API_KEY',
  purchaseConfig: createRevenueCatPurchaseConfig({ apiKey: 'YOUR_REVENUECAT_API_KEY' }),
  revenueCatAppUserId: await Purchases.getAppUserID(),
});

// Option B: initialize RevenueCat yourself first, then omit apiKey
await initialize({
  apiKey: 'YOUR_API_KEY',
  purchaseConfig: createRevenueCatPurchaseConfig(),
  revenueCatAppUserId: await Purchases.getAppUserID(),
});

Keeping appUserID in sync

If you change the RevenueCat appUserID, sync the value to Helium:

import { setRevenueCatAppUserId } from 'expo-helium';

setRevenueCatAppUserId(await Purchases.getAppUserID());

---

Custom Purchase Handling

By default, Helium handles purchases for you. This section is for apps that need custom purchase logic.

Pass createCustomPurchaseConfig to initialize:

Expo 52+ (separate iOS / Android handlers)

import { createCustomPurchaseConfig } from 'expo-helium';

await initialize({
  apiKey: 'YOUR_API_KEY',
  purchaseConfig: createCustomPurchaseConfig({
    makePurchaseIOS: async (productId) => {
      // Your iOS purchase logic
      return { status: 'purchased' };
    },
    makePurchaseAndroid: async (productId) => {
      // Your Android purchase logic
      return { status: 'purchased' };
    },
    restorePurchases: async () => true,
  }),
});

import { createCustomPurchaseConfig } from '@tryheliumai/paywall-sdk-react-native';

await initialize({
  apiKey: 'YOUR_API_KEY',
  purchaseConfig: createCustomPurchaseConfig({
    makePurchase: async (productId) => {
      // Your purchase logic
      return { status: 'purchased' };
    },
    restorePurchases: async () => true,
  }),
});

makePurchase must return one of the following statuses:

type HeliumTransactionStatus =
  'purchased' | 'failed' | 'cancelled' | 'pending' | 'restored';

---

Additional Methods

Reset Helium

Resets Helium so initialize can be called again. Useful after changing user traits that affect paywall targeting.

import { resetHelium } from 'expo-helium';

await resetHelium();

---

Troubleshooting

Verify the package is installed

Expo 52+

[ -d "node_modules/expo-helium" ] \
  && echo "✅ expo-helium found" \
  || echo "❌ expo-helium NOT found"

[ -d "node_modules/@tryheliumai/paywall-sdk-react-native" ] \
  && echo "✅ paywall-sdk-react-native found" \
  || echo "❌ paywall-sdk-react-native NOT found"

If not found, reinstall using the commands in Step 1.

Verify the native pod is installed

Expo 52+

grep -E "Helium" ios/Podfile.lock > /dev/null \
  && echo "✅ Helium found in Podfile.lock" \
  || echo "❌ Helium not found in Podfile.lock" \
&& grep -E "HeliumPaywallSdk" ios/Podfile.lock > /dev/null \
  && echo "✅ HeliumPaywallSdk found in Podfile.lock" \
  || echo "❌ HeliumPaywallSdk not found in Podfile.lock"

grep -E "Helium" ios/Podfile.lock > /dev/null \
  && echo "✅ Helium found in Podfile.lock" \
  || echo "❌ Helium not found in Podfile.lock"

If Helium isn’t found in Podfile.lock, regenerate the native directories and rebuild:

npx expo prebuild --clean
npx expo run:ios   # or npx expo run:ios --device