​
Background

Get set up with the Helium SDK for iOS in 5 minutes. Reach out over your Helium slack channel, or email founders@tryhelium.com for any questions.

​
Installation

Install the SDK using your preferred package manager:

npx expo install expo-helium

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

If on Expo 52+, do not add HeliumProvider.

HeliumProvider needed ONLY if using @tryheliumai/paywall-sdk-react-native (older Expo versions OR bare React Native).

​
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.

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;
        }
      }),

      // Event handler for paywall events
      onHeliumPaywallEvent: (event) => {
        switch (event.type) {
          case 'paywallOpen':
            break;
          case 'ctaPressed':
            if (event.ctaName === HELIUM_CTA_NAMES.SCHEDULE_CALL) {
              // Handle schedule call
            }
            break;
          case 'subscriptionSucceeded':
            // Handle successful subscription
            break;
        }
      },

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

}

​
Use RevenueCat with Helium

Important Make sure that you’ve already:

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

const asyncHeliumInit = async () => {
  initialize({
    apiKey: '<your-helium-api-key>',
    customUserId: '<your-custom-user-id>', // (optional)
    purchaseConfig: createRevenueCatPurchaseConfig(),
    onHeliumPaywallEvent: (event) => {
      switch (event.type) {
        case 'subscriptionFailed':
          // Custom logic
          break;
        case 'subscriptionSucceeded':
          // Handle a subscription 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 a dictionary specifying the triggerName as well as an optional onFallback parameter defining custom fallback behavior (in case the user didn’t have a network connection)

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} />
  );
}

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

​
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

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

If the package is not found, install it again:

npx expo install expo-helium

​
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"

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