Skip to main content

​
Background

Get set up with the Helium SDK for React Native. Reach out over your Helium slack channel or email [email protected] for any questions.
The Helium React Native SDK currently supports iOS only. Android support is expected mid- to late-November.

​
Installation

Install the SDK using your preferred package manager: 
npx expo install expo-helium
We support Expo 49+ but 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.

​
Initialization

Initialize Helium by calling initialize() early in your app’s lifecycle, typically in your root component.
If you are using RevenueCat, follow the example in the next section.
import { initialize } from 'expo-helium';

function App() {
  useEffect(() => {
    initialize({
      apiKey: '<your-helium-api-key>',
      // Fallback bundle is highly recommended. See Fallbacks section of this page.
      // fallbackBundle: require('./assets/fallback-bundle-xxxx-xx-xx.json'),
    });
  }, []);
}

​
Use RevenueCat with Helium

If you haven’t already, make sure to install RevenueCat (for non-Expo see here).
import { initialize } from 'expo-helium';
import { createRevenueCatPurchaseConfig } from "expo-helium/src/revenuecat";

const asyncHeliumInit = async () => {
  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' }
    ),
    // Fallback bundle is highly recommended. See Fallbacks section of this page.
    // fallbackBundle: require('./assets/fallback-bundle-xxxx-xx-xx.json'),
    revenueCatAppUserId: await Purchases.getAppUserID()
  });
};

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

​
Custom Purchase Config

To use your own purchase logic, pass in a custom purchase config to initialize: 
import { createCustomPurchaseConfig } from 'expo-helium';

// In your initialize call:
purchaseConfig: createCustomPurchaseConfig({
  // NOTE - on version 3.1.0+ makePurchase is deprecated in favor of
  // makePurchaseIOS and makePurchaseAndroid
  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';

​
Custom User ID and Custom User Traits

You can pass in a custom user ID and custom user traits if desired to initialize: 
// (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",
},

​
Presenting Paywalls

You must have a trigger and workflow configured in the dashboard in order to show a paywall.
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 or display error dialog
        console.log('[Helium] onFallback called!');
      }
    });
  };

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

​
PaywallEventHandlers

You can pass in paywall event handlers to listen for specific paywall events. (See the next section Helium Events for a way to handle global events). 
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.
  },
},
You should now be able to see Helium paywalls in your app! Well done! 🎉

​
Helium Events

Listen for all Helium Events by implementing onHeliumPaywallEvent and passing it to initialize: 
onHeliumPaywallEvent: (event) => {
  switch (event.type) {
    case 'paywallOpen':
      break;
    case 'purchaseSucceeded':
      // Handle successful purchase
      break;
    // handle other events as desired
  }
},

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

/**
 * Checks if the user has an active entitlement for any product attached to the paywall that will show for provided trigger.
 * @param trigger The trigger name to check entitlement for
 * @returns Promise resolving to true if entitled, false if not, or undefined if not known (i.e. the paywall is not downloaded yet)
 */
export const hasEntitlementForPaywall = async (trigger: string): Promise<boolean | undefined>;

​
Example Usage

Check entitlements before showing paywalls to avoid showing a paywall to a user who should not see it.
presentUpsell({
  triggerName: 'my_paywall',
  dontShowIfAlreadyEntitled: true
});

​
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 7 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",
  fallbackBundle: require('./assets/fallback-bundle-xxxx-xx-xx.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

​
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