To get a better understanding of how paywalls are served, visit here.

Present a Paywall

Install the SDK

Install the SDK using your preferred package manager:

npx expo install expo-helium

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

# [Bare only] then run the following to install the native dependencies
npx react-native link @tryheliumai/paywall-sdk-react-native

We support Expo 49+ but recommend using Helium with Expo 53+.

The Older Expo / Bare SDK supports iOS only.The Expo 52+ SDK supports both iOS and Android.

Initialize Helium

Find your API key here. If you do not have a Helium account set up yet, you can still integrate but will not be able to show a real paywall.

Initialize Helium by calling initialize() early in your app’s lifecycle, typically in your root component:

import { initialize } from 'expo-helium';

function App() {
  const asyncHeliumInit = async () => {
    await initialize({
      apiKey: '<your-helium-api-key>',
    });
  };

  useEffect(() => {
    void asyncHeliumInit();
  }, []);
}

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

function App() {
  const asyncHeliumInit = async () => {
    await initialize({
      apiKey: '<your-helium-api-key>',
    });
  };

  useEffect(() => {
    void asyncHeliumInit();
  }, []);
}

Show Your First Paywall 🎉

Set up a trigger and workflow in the dashboard to show your desired paywall. Create unique triggers for each location a paywall can show in your app! This provides more flexibility with paywall variation and experiments, allowing you to take full advantage of Helium.

Call presentUpsell wherever you want to show a full-screen paywall:

import { presentUpsell } from 'expo-helium';

function YourComponent() {
  const handlePremiumPress = () => {
    presentUpsell({
      triggerName: 'premium_feature_press',
    });
  };

  return (
    <Button title="Try Premium" onPress={handlePremiumPress} />
  );
}

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

function YourComponent() {
  const handlePremiumPress = () => {
    presentUpsell({
      triggerName: 'premium_feature_press',
    });
  };

  return (
    <Button title="Try Premium" onPress={handlePremiumPress} />
  );
}

PresentUpsellParams

type

Show properties

triggerName

string

required

Pass in the trigger for the workflow you configured in the dashboard.

eventHandlers

PaywallEventHandlers?

(Optional) Handlers that allow you to respond to open, close, dismiss, purchase, open-fail, and custom paywall action events.

customPaywallTraits

Record<string, any>?

(Optional) Custom key/value pairs that you want available to the paywall.

dontShowIfAlreadyEntitled

boolean?

default:"false"

(Optional) If true, the paywall will not be shown if the user already has an entitlement for a product in the paywall. In most cases the default of false is desired — see “Checking Subscription Status & Entitlements” below before enabling this.

onEntitled

(() => void)?

(Optional) Called upon purchase success or purchase restore. If dontShowIfAlreadyEntitled is true, this handler will also be called when the paywall is not shown to users who already have entitlement for a product in the paywall.

onPaywallUnavailable

(() => void)?

(Optional) Called if desired paywall and fallback paywall did not show for any reason. This is uncommon, but best practice to handle it just in case. See Fallback Paywalls.

You should now be able to see Helium paywalls in your app! Well done! 🎉

Looking for alternative presentation methods? Check out the guide on Ways to Show a Paywall.

Recommended Setup

Here are some common additional steps that you may want to consider.

Identifying Users

Identifying users is optional but can help with targeting and when forwarding events to external analytics platforms. If you are not sure, you probably do not need to identify your users.

Identify users as early as you can to maximize consistency in metrics and targeting. Ideally in your initialize call!

await initialize({
  apiKey: '<your-helium-api-key>',
  // (Optional) Custom user id, e.g. your amplitude analytics user id.
  customUserId: '<your-custom-user-id>',
  // (Optional) Custom user traits
  customUserTraits: {
    "example_trait": "example_value",
  },
});

import { setCustomUserId } from 'expo-helium';

setCustomUserId('your-custom-user-id');

Helium Events

Helium dispatches various events during paywall presentation and purchase flow. You can optionally handle these events in your mobile app. You can also configure Helium to forward them to your existing analytics provider.

PaywallEventHandlers

When displaying a paywall you can pass in event handlers to listen for select events:

presentUpsell({
  triggerName: 'my_paywall',
  eventHandlers: {
    onOpen: (event) => {
      console.log(`${event.type}`)
    },
    onClose: (event) => {
      console.log(`${event.type}`)
    },
    onPurchaseSucceeded: (event) => {
      console.log(`${event.type}`)
    },
    onDismissed: (event) => {
      console.log(`${event.type}`)
    },
    onOpenFailed: (event) => {
      console.log(`${event.type}`)
    },
    onCustomPaywallAction: (event) => {
      console.log(`${event.type}`)
    },
    onAnyEvent: (event) => {
      // A handler for all paywall-related events.
      // Note that if you have other handlers (i.e. onOpen) set up,
      // both that handler AND this one will fire during paywall open.
    },
  },
});

Global Event Listener

You can also listen for all Helium events globally by passing onHeliumPaywallEvent to initialize:

await initialize({
  apiKey: '<your-helium-api-key>',
  onHeliumPaywallEvent: (event) => {
    switch (event.type) {
      case 'paywallOpen':
        break;
      case 'purchaseSucceeded':
        // Handle successful purchase
        break;
      // handle other events as desired
    }
  },
});

Fallback Paywalls

It is highly recommended that you set up “fallbacks” to handle the rare case when a paywall fails to display. Please follow this guide to do so.

Do this after you have a paywall created that you want to use in production.

Checking Subscription Status & Entitlements

Helium checks entitlements directly through the underlying app store (StoreKit on iOS, Google Play Billing on Android) and provides helper methods to make this easier. Consider checking entitlements to gate premium features.

If you have a backend server that manages user entitlements, you may have no use for these helpers.

All Entitlement Helper Methods

/**
 * Checks if the user has any active subscription (including non-renewable)
 */
export const hasAnyActiveSubscription = async (): Promise<boolean>;

/**
 * Checks if the user has any entitlement
 */
export const hasAnyEntitlement = async (): Promise<boolean>;

/**
 * Checks if the user has an active entitlement for any product attached to
 * the paywall that will show for the provided trigger.
 * Returns undefined if not known (i.e. the paywall is not downloaded yet).
 */
export const hasEntitlementForPaywall = async (trigger: string): Promise<boolean | undefined>;

If you want to check entitlement status before presenting a paywall, here are a couple of ways to do so.

For paywalls that are user-initiated (e.g. “Upgrade to Premium”) and onboarding paywalls, checking entitled status is not recommended. Apps usually want to consistently show a paywall for these locations, and users can still “Restore Purchases” as needed.

presentUpsell({
  triggerName: 'my_paywall',
  dontShowIfAlreadyEntitled: true
});

const hasActiveSubscription = await hasAnyActiveSubscription();
if (hasActiveSubscription) {
  featureGatedLogic(); // replace this with your logic
} else {
  presentUpsell({
    triggerName: 'my_paywall',
    eventHandlers: {
      onPurchaseSucceeded: (event: PurchaseSucceededEvent) => {
        featureGatedLogic(); // replace this with your logic
      },
    },
  });
}

Advanced

RevenueCat

By default, Helium will handle purchases for you! This section is typically for users who already use RevenueCat in their app.

Helium integrates seamlessly with RevenueCat so you can continue to let RevenueCat handle your purchases and entitlements.

If you haven’t already, make sure to install RevenueCat (for non-Expo see here).Make sure to initialize RevenueCat (Purchases.configure()) before initializing Helium.

Configure Helium to use RevenueCat by passing createRevenueCatPurchaseConfig to initialize:

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

const asyncHeliumInit = async () => {
  await initialize({
    apiKey: '<your-helium-api-key>',
    purchaseConfig: createRevenueCatPurchaseConfig(),
    revenueCatAppUserId: await Purchases.getAppUserID()
  });
};

useEffect(() => {
  void asyncHeliumInit();
}, []);

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

const asyncHeliumInit = async () => {
  await initialize({
    apiKey: '<your-helium-api-key>',
    purchaseConfig: createRevenueCatPurchaseConfig(
      // (optional) Set if you want Helium to initialize RevenueCat for you.
      // Otherwise initialize RevenueCat (`Purchases.configure()`) before initializing Helium
      { apiKey: 'revenue_cat_api_key' }
    ),
    revenueCatAppUserId: await Purchases.getAppUserID()
  });
};

useEffect(() => {
  void asyncHeliumInit();
}, []);

RevenueCat appUserID

If you ever change the appUserID of a user, keep Helium in sync with:

import { setRevenueCatAppUserId } from 'expo-helium';

setRevenueCatAppUserId(await Purchases.getAppUserID());

Custom Purchase Handling

By default, Helium will handle purchases for you! This section is for those who want to implement custom purchase logic.

Pass a custom purchase config to initialize:

import { createCustomPurchaseConfig } from 'expo-helium';

// In your initialize call:
purchaseConfig: createCustomPurchaseConfig({
  makePurchaseIOS: async (productId) => {
    // Your purchase logic here
    // Return a HeliumTransactionStatus
    return { status: 'purchased' };
  },
  makePurchaseAndroid: async (productId) => {
    // Your purchase logic here
    // Return a HeliumTransactionStatus
    return { status: 'purchased' };
  },
  restorePurchases: async () => {
    // Your restore logic here
    return true;
  }
}),

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

// In your initialize call:
purchaseConfig: createCustomPurchaseConfig({
  makePurchase: async (productId) => {
    // Your purchase logic here
    // Return a HeliumTransactionStatus
    return { status: 'purchased' };
  },
  restorePurchases: async () => {
    // Your restore logic here
    return true;
  }
}),

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

Additional Features

For the full public API and detailed parameter documentation, see the inline docstrings in the SDK source. Import Helium in your project and use your IDE’s autocomplete or jump-to-definition to explore all available methods and types.

Hiding Paywalls Programmatically

You can programmatically hide paywalls using:

// Hide the current paywall
hideUpsell();

// Hide all currently displayed paywalls
hideAllUpsells();

Reset Helium

Reset Helium entirely so you can call initialize again, for example after changing user traits that can affect the paywalls a user might see via targeting.

import { resetHelium } from 'expo-helium';

await resetHelium();

Expo Development Build

Please note that the Helium SDK uses native code, so you must create a development build. A common command to run for this is:

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

Troubleshooting

Check if the Helium SDK is installed

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

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

If the package is not found, install it again:

npx expo install expo-helium

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

# then run the following to install the native dependencies
npx react-native link @tryheliumai/paywall-sdk-react-native

Check if Helium is properly installed

To verify that the Helium pod is correctly installed in your project, run:

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

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

If not found, try these commands:

# regenerate the ios (and android) directories
npx expo prebuild --clean

# run a development build
npx expo run:ios # or npx expo run:ios --device

​Present a Paywall

​Install the SDK

​Initialize Helium

​Show Your First Paywall 🎉

​Recommended Setup

​Identifying Users

​Helium Events

​PaywallEventHandlers

​Global Event Listener

​Fallback Paywalls

​Checking Subscription Status & Entitlements

​Advanced

​RevenueCat

​RevenueCat appUserID

​Custom Purchase Handling

​Additional Features

​Expo Development Build

​Troubleshooting

​Check if the Helium SDK is installed

​Check if Helium is properly installed

Present a Paywall

Install the SDK

Initialize Helium

Show Your First Paywall 🎉

Recommended Setup

Identifying Users

Helium Events

PaywallEventHandlers

Global Event Listener

Fallback Paywalls

Checking Subscription Status & Entitlements

Advanced

RevenueCat

RevenueCat appUserID

Custom Purchase Handling

Additional Features

Expo Development Build

Troubleshooting

Check if the Helium SDK is installed

Check if Helium is properly installed