Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roycewilliams.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
What are “fallbacks”?

The Helium SDK does its best to fetch the latest paywalls to display in your app. But if for some reason a paywall is not available — perhaps if an app user temporarily did not have a data connection — Helium will attempt to show a “fallback”. You can download copies of your actual Helium paywalls and include that in your app to use in the rare case that a Helium paywall is not ready for display.

​
Download Fallbacks

Go to the Workflows page in your dashboard and find the Download Fallbacks button: Download Fallbacks 1 Pn This will open a dialog and allow you to select which paywall/s to use as fallback. Most of the time you only need to set Default Fallbacks. After selection, click Download and your browser should download a file named helium-fallbacks.json.
Whenever you update paywalls consider whether you want to repeat this process to update your fallbacks.

​
Add fallbacks to your Helium SDK integration

  1. Integrate the SDK with the iOS Quickstart if you haven’t done so already.
  2. Drag your downloaded file into the Project navigator of your Xcode project.
  3. You should see a dialog with Action and Targets fields. For Action, select your preference between the move and copy options. For Targets ensure that your app’s main target is selected.
  4. That’s it! The SDK automatically detects any file with the name helium-fallbacks.json.
To use a custom file name, set it before calling initialize():
Helium.config.customFallbacksURL = Bundle.main.url(
    forResource: "fallback-bundle-xxxx-xx-xx",
    withExtension: "json"
)

​
Testing Fallbacks

Look at your debug log output when running a debug build of your app to see if fallbacks are successfully loaded. To see a fallback paywall, you can run your app in airplane mode or use a non-existent trigger when presenting a paywall.

​
How to Monitor and Minimize Fallback Rate

You can check your app’s fallback rate by going to your Metrics page and clicking on the “Fallback Rate” tab under Monitoring. This rate shows the percentage of paywall opens that use a fallback paywall. If you notice your fallback rate is higher than expected, here are some tips on minimizing it:
  • Move your initialize() call earlier in your app’s lifecycle. We recommend doing so right when your app is launched.
  • Set a higher loading budget. If your paywall is still downloading when presented, Helium will show a loading state. The default loading budget of 7 seconds is generally plenty of time to ensure your paywall will show before fallback is used. But if you have overridden the budget to be a lower value, consider increasing it.
  • Reduce the size of image assets in your paywall. We recommend keeping each paywall to be under about 3-5 MB in total size. If you’re adding high resolution imagery to your paywall (which is fine!) we recommend converting images to .webp format - e.g. with an online converter like https://cloudconvert.com/webp-converter.
If you still see a rate higher than expected, please get in touch!

​
Fallback Causes

​
Paywall is still downloading

This is the most common reason.
Helium fetches your latest paywalls when the Helium SDK is initialized. If a user is on a very slow connection or has no connection at all, a fallback will be shown.

​
Paywalls failed to download

Similarly, if user has no connection or a very limited connection, the paywall retrieval may fail entirely. Or in the unlikely event Helium servers are temporarily down.

​
No products associated with paywall for platform

Can occur when a paywall is downloaded but does not have products properly linked for the platform (iOS/Android) it is served to.

​
Other Causes

The above are the most likely causes, but a fallback can also occur if paywall html is malformed or from any other unexpected Helium bug.