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:
This will open a dialog and allow you to select which paywall/s to use as fallback.
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
iOS
Android
React Native
Flutter
- Integrate the SDK with the iOS Quickstart if you haven’t done so already.
- Drag your downloaded file into the Project navigator of your Xcode project.
- 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.
- 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"
)
- Integrate the SDK with the Android Quickstart if you haven’t done so already.
- In your app’s
src/main directory, create an assets folder if one doesn’t already exist.
- Drag your downloaded bundle into the
assets folder.
- That’s it! The SDK automatically detects
helium-fallbacks.json in your assets.
To use a custom file name, set it before calling initialize():Helium.config.customFallbacksFileName = "fallback-bundle-xxxx-xx-xx.json"
- Integrate the SDK with the React Native Quickstart if you haven’t done so already.
- Drag your downloaded bundle into your React Native project where desired.
- Pass in to
Helium.initialize
const fallbackBundle = require('./assets/fallback-bundle-xxxx-xx-xx.json');
initialize(
apiKey: apiKey,
// ... other parameters ...
fallbackBundle: fallbackBundle,
)
Make sure to use the correct path and filename in your require call!
- Integrate the SDK with the Flutter Quickstart if you haven’t done so already.
- Drag your downloaded bundle into your Flutter project where desired.
- In your
pubspec.yaml add the new asset:
assets:
- .env
- fallback-bundle-xxxx-xx-xx.json # add this line
- Pass in to
Helium.initialize
heliumFlutter.initialize(
// ... other parameters ...
fallbackBundleAssetPath: "fallback-bundle-xxxx-xx-xx.json"
Make sure to use the correct filename in both pubspec.yaml and the call to initialize!
Testing Fallbacks
In version 4+ of the SDKs, look at your log output when running a test build to see if fallbacks are successfully loaded.
You can also run your app in airplane mode and then attempt to show your paywall, or show your paywall with a non-existent trigger.
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 # of fallback paywall opens vs prod paywall opens. 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 right after app launch.
- 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!
