Skip to main content
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 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

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.
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",
      },
    });
  }, []);
}

​
Use RevenueCat with Helium

Important Make sure that you’ve already: 
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();
}, []);

​
Presenting Paywalls

Use the presentUpsell method to present a paywall. presentUpsell takes in PresentUpsellParams:
​
PresentUpsellParams
method
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! 🎉

​
Checking Subscription Status & Entitlements

Use these methods to check current user subscription status. 
/**
 * 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>;

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

[ -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
⌘I