Skip to main content

​
Overview

Helium’s event handling system has native handlers for most common paywall events (purchases, navigation, etc), but in some cases you might want to have custom interactions on your paywall that aren’t handled by default. For example, you might want to have a toggle that when selected sends a trial notification reminder using your own notification system. Helium lets you do this with Custom Events.

​
Custom Events

A custom event is fired from the paywall and handled from the SDK. You can have as many different types of custom events as you want within a single paywall. Custom events have a few properties: Action Name - (String) The name of the event. For example, “did_switch_trial_toggle” Params - (Dictionary of string keys -> any type of value) Dictionary of arbitrary parameters associated with the action. The keys have to be strings, the values can be numbers, boolean, strings, arrays, or dictionaries themselves. For example, 
{
  "is_toggle_selected": False,
  "iso_timestamp": 13041241255
}
We recommend asking the editor to separate out different interactions into different actions. For example, if you have
  • a trial notification toggle
  • a little survey that you ask the user within the paywall
  • a custom dismiss button
Separating these out into different actions with their own parameters will make it easier to handle from the SDK side. There are two steps to setting up custom event handling with Helium:

​
Editor: Add a button that emits a custom action to your paywall

In the Helium paywall editor, you can add a button or interaction that sends a custom action by just asking the chat. For example,
  • Add a trial reminder toggle using custom actions.
  • Add a button that triggers requesting permissions for location if a user press an opt in button.
  • Make it so that if the user selects the Watch Ads button, the editor sends a custom action to handle so that the SDK can handle that case on purchase pressed ”
Some tips:
  • You can verify the editor is using a custom action using the Actions Panel.
  • Feel free to tell the editor the specific action name and params you want it to use!
  • Reach out to support with your use case - happy to set this up for you and tell you what the corresponding SDK code should look like to handle the new event!

​
SDK: Add an onCustomPaywallAction handler

Then, within your SDK you can use Paywall Event Handlers with the onCustomPaywallAction event. Visit our SDK’s quickstart pages for more info on getting set up with the SDK.
  • iOS
  • Android
Helium.shared.presentUpsell(
    trigger: "your_trigger",
    eventHandlers: PaywallEventHandlers()
        .onCustomPaywallAction { event in
            if event.actionName == "your_action_name",
               let value = event.params["key1"] as? String {
                // Handle your custom action
                // E.g., mark that we should send a notification on purchase
                print("Received: \(value)")
            }
        }
)
The CustomPaywallActionEvent contains:
  • actionName: The action name
  • params: Dictionary of parameters
  • triggerName: The trigger that opened this paywall
  • paywallName: The name of the paywall
  • timestamp: ISO timestamp for when the event occurred