Fallbacks

Handle offline scenarios and network failures gracefully

A fallback paywall is a safety net. If the Helium SDK can’t load the intended paywall — due to a slow connection, a timeout, or the user going offline — it shows a fallback instead. This ensures your users always see a paywall, even in imperfect network conditions.

---

How It Works

1. You download a fallback bundle from the Workflows page in the Helium dashboard.
2. You include the bundle in your app and pass it to the SDK during initialization.
3. If the SDK can’t fetch or display the live paywall in time, it shows the fallback.

The fallback is a fully functional paywall — users can still subscribe, restore purchases, and dismiss. It just happens to be pre-bundled with the app rather than fetched from the server.

---

Configuring Fallbacks

From the Workflows page, click Download Fallbacks. You’ll configure:

Setting	Description
iOS default fallback	The paywall shown on iOS when no trigger-specific fallback matches.
Android default fallback	The paywall shown on Android when no trigger-specific fallback matches.
Per-trigger fallbacks (optional)	Override the default for specific triggers — useful if different triggers show very different paywalls.

The download produces a helium-fallbacks.json file that you add to your app’s assets.

---

Monitoring Fallback Rate

Helium tracks your Fallback Rate — the percentage of paywall sessions that served a fallback instead of the live paywall. You’ll find it in the Monitoring section of your metrics.

A healthy fallback rate is as close to 0% as possible. If it’s elevated, the most common fixes are:

Lever	What it does
Call initialize() earlier	Start the SDK sooner (e.g., at app launch) so paywalls are pre-fetched before the user triggers one.
Increase the loading budget	Give the SDK more time to download the paywall before falling back. The default is 7 seconds.
Update your fallback bundle	Re-download and ship an updated fallback when you change your paywalls, so the fallback stays current.

---

Key Points

• Fallbacks are fully functional — subscriptions work normally.

• Fallback sessions are tracked separately in analytics so they don’t skew your paywall metrics.

• Keep your fallback bundle up to date — re-download it when you publish significant paywall changes.

• A low fallback rate means the SDK is loading paywalls successfully before users need them.