SDK Quickstart (React Native)

Integrate Helium into your React Native App.

Using an older SDK version?

If you’re upgrading from SDK v0.x, check our Migration Guide for breaking changes and upgrade instructions.

Background

Get set up with the Helium SDK for React Native. Reach out over your Helium slack channel or email [e-mail] for any questions.

Installation

Install the SDK using your preferred package manager:

Expo 52+

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 do recommend using Helium with Expo 53 and up. If you’re on an older version and having issues, ping us - we’ve got experience with all kinds of versioning, upgrade, and custom build plugin work.

Configuration

Follow these steps to integrate the SDK.

HeliumProvider

HeliumProvider is no longer needed in v3.0+. See our Migration Guide.

Initialization

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

If you are using RevenueCat, check out the example in the next section.

Expo 52+

import { initialize, createCustomPurchaseConfig, HELIUM_CTA_NAMES } from 'expo-helium';

function App() {
  useEffect(() => {
    initialize({
      apiKey: '<your-helium-api-key>',
      // (Optional) Custom user id, e.g. your amplitude analytics user id.
      customUserId: '<your-custom-user-id>',
      purchaseConfig: createCustomPurchaseConfig({
        makePurchase: async (productId) => {
          // Your purchase logic here
          return { status: 'purchased' };
        },
        restorePurchases: async () => {
          // Your restore logic here
          return true;
        }
      }),

      // Example event handler for paywall events
      onHeliumPaywallEvent: (event: HeliumPaywallEvent) => {
        switch (event.type) {
          case 'paywallOpen':
            break;
          case 'paywallButtonPressed':
            if (event.buttonName === HELIUM_CTA_NAMES.SCHEDULE_CALL) {
              // Handle schedule call
            }
            break;
          case 'purchaseSucceeded':
            // Handle successful purchase
            break;
        }
      },

      // (Optional) Custom user traits
      customUserTraits: {
        "example_trait": "example_value",
      },
    });
  }, []);
}

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

function App() {
  const asyncHeliumInit = async () => {
    initialize({
      apiKey: '<your-helium-api-key>',
      // (Optional) Custom user id, e.g. your amplitude analytics user id.
      customUserId: '<your-custom-user-id>',
      purchaseConfig: createCustomPurchaseConfig({
        makePurchase: async (productId) => {
          // Your purchase logic here
          return { status: 'purchased' };
        },
        restorePurchases: async () => {
          // Your restore logic here
          return true;
        }
      }),

      // Event handler for paywall events
      onHeliumPaywallEvent: (event) => {
        switch (event.type) {
          case 'paywallOpen':
            break;
          case 'paywallButtonPressed':
            if (event.buttonName === HELIUM_CTA_NAMES.SCHEDULE_CALL) {
              // Handle schedule call
            }
            break;
          case 'purchaseSucceeded':
            // Handle successful purchase
            break;
        }
      },

      // (Optional) Custom user traits
      customUserTraits: {
        "example_trait": "example_value",
      },
    });
  };

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

Use RevenueCat with Helium

Important Make sure that you’ve already:

• Installed RevenueCat (if non-Expo go here)
• (Recommended) Configured an Entitlement

Expo 52+

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

const asyncHeliumInit = async () => {
  initialize({
    apiKey: '<your-helium-api-key>',
    customUserId: '<your-custom-user-id>', // (optional)
    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' }
    ),
    onHeliumPaywallEvent: (event: HeliumPaywallEvent) => {
      switch (event.type) {
        case 'purchaseFailed':
          // Custom logic
          break;
        case 'purchaseSucceeded':
          // Handle a purchase success event
          // e.g. navigate to a premium page
          break;
      }
    },
    revenueCatAppUserId: await Purchases.getAppUserID()
  });
};

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

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

const asyncHeliumInit = async () => {
  initialize({
    apiKey: '<your-helium-api-key>',
    customUserId: '<your-custom-user-id>', // (optional)
    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' }
    ),
    onHeliumPaywallEvent: (event: HeliumPaywallEvent) => {
      switch (event.type) {
        case 'purchaseFailed':
          // Custom logic
          break;
        case 'purchaseSucceeded':
          // Handle a purchase success event
          // e.g. navigate to a premium page
          break;
      }
    },
    revenueCatAppUserId: await Purchases.getAppUserID()
  });
};

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

Presenting Paywalls

Use the presentUpsell method to present a paywall. presentUpsell takes in PresentUpsellParams:

PresentUpsellParams · method

Show properties

triggerName · string · required

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

onFallback · () => void

This will be called when paywall fails to show due to an unsuccessful paywall download or if an invalid trigger is provided. (See Fallbacks section for more details.)

eventHandlers · PaywallEventHandlers

Handlers that allow you to respond to open, close, dismiss, and purchase events.

customPaywallTraits · Record<string, any>

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

Expo 52+

import { presentUpsell } from 'expo-helium';

function YourComponent() {
  const handlePremiumPress = () => {
    presentUpsell({
      triggerName: 'premium_feature_press',
      onFallback: () => {
        // Implement logic to open a default paywall
        console.log('[Helium] onFallback called!');
      }
    });
  };

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

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

function YourComponent() {
  const handlePremiumPress = () => {
    presentUpsell({
      triggerName: 'premium_feature_press',
      onFallback: () => {
        // Implement logic to open a default paywall
        console.log('[Helium] onFallback called!');
      }
    });
  };

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

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

Fallbacks

There are currently two ways you can handle a “fallback” situation in the rare case that a paywall fails to download or an invalid trigger is provided. You can also do both. Better to be prepared!

1. Use the onFallback function

You can pass this in when you call presentUpsell and handle however you want.

2. Provide a fallback bundle (recommended)

Provide a fallback bundle as described in this guide.

Update your fallback bundle whenever you make changes to your paywall for maximum reliability.

Loading Budgets

If a paywall has not completed downloading when you attempt to present it, a loading state can show.

By default, Helium will show this loading state as needed (a shimmer view for up to 2 seconds). You can configure, turn off, or set trigger-specific loading budgets.

If the budget expires before the paywall is ready, a fallback paywall will show if available otherwise the loading state will hide and onFallback will be called.

const paywallLoadingConfig: HeliumPaywallLoadingConfig = {
  useLoadingState: true,
  loadingBudget: 4,
  perTriggerLoadingConfig: {
    "onboarding": {
      loadingBudget: 5,
    },
    "trial": {
      useLoadingState: false,
    }
  },
};

initialize({
  apiKey: "helium-api-key",
  purchaseConfig: createRevenueCatPurchaseConfig(
    {apiKey: 'rc-api-key'}
  ),
  onHeliumPaywallEvent: (event: HeliumPaywallEvent) => {
    console.log('Helium Paywall Event:', event);
  },
  fallbackBundle: require('./assets/fetched.json'),
  paywallLoadingConfig: paywallLoadingConfig, // << pass to initialize
});

Additional Considerations

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

Paywall Events

Helium emits various events during the lifecycle of a paywall. If desired, you can handle these events in the onHeliumPaywallEvent callback. See Helium Events for more details.

Troubleshooting

Check if the Helium SDK is installed

Expo 52+

[ -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:

Expo 52+

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:

Expo 52+

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