> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhelium.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Helium is a paywall platform for mobile apps. Paywalls, workflows, triggers, targeting and experiments are configured in the dashboard (https://app.tryhelium.com); the SDK's job is to initialize, present a paywall for a trigger, and report purchases.
> Pick the SDK page for the user's platform: /sdk/quickstart-ios (Swift), /sdk/quickstart-android (Kotlin), /sdk/quickstart-react-native, /sdk/quickstart-flutter. Method names differ per platform; copy them from the page for that platform, never from another platform's page.
> Pages under /sdk/quickstart-ios-v3 and /sdk/quickstart-android-v0 are legacy SDK versions. Use them only when the user is on that version; for upgrades use the /migrations pages.
> For live dashboard data (paywalls, workflows, metrics) connect the Helium MCP server at https://app.tryhelium.com/api/mcp (see /ai-tools/mcp). For SQL over events, revenue, subscriptions and users use the Data Access API (/data-access/overview) and the helium-data-access skill (/data-access/agent-skill). This documentation site also exposes a docs-search MCP server at https://docs.tryhelium.com/mcp.
> Web checkout (App2Web) with Stripe or Paddle is a separate flow from in-app purchases; start at /web-checkout/overview.
> Every page is available as Markdown by appending .md to its URL. The full index is at https://docs.tryhelium.com/llms.txt.

# Handling Custom Paywall Events

> Send custom events from your paywall to your app to trigger actions beyond purchases.

## 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.

> [tab] iOS
>
> ```swift theme={null}
> Helium.shared.presentPaywall(
>     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

> [tab] Android
>
> ```kotlin theme={null}
> import com.tryhelium.paywall.core.event.PaywallEventHandlers
> import kotlinx.serialization.json.jsonPrimitive
> import kotlinx.serialization.json.contentOrNull
>
> Helium.shared.addPaywallEventListener(
>     lifecycleOwner = this, // Your activity or fragment
>     listener = PaywallEventHandlers(
>         onCustomPaywallAction = { event ->
>             if (event.actionName == "your_action_name") {
>                 // Extract a string value from the params
>                 val value = event.params["key1"]?.jsonPrimitive?.contentOrNull
>
>                 // Handle your custom action
>                 Log.d("PaywallEvents", "Received custom action with value: $value")
>             }
>         }
>     )
> )
> ```
>
> The `CustomPaywallAction` event contains:
>
> * `actionName`: The name of the event.
> * `params`: A `JsonObject` of arbitrary parameters associated with the action.
> * `triggerName`: The trigger that opened this paywall.
> * `paywallName`: The name of the paywall.
> * `timestamp`: Unix timestamp for when the event occurred.

> [tab] React Native
>
> ```typescript theme={null}
> import { presentUpsell } from 'expo-helium';
> // or: import { presentUpsell } from '@tryheliumai/paywall-sdk-react-native';
>
> presentUpsell({
>   triggerName: 'your_trigger',
>   eventHandlers: {
>     onCustomPaywallAction: (event) => {
>       if (event.actionName === 'your_action_name') {
>         const value = event.params.key1;
>         // Handle your custom action
>         console.log('Received:', value);
>       }
>     },
>   },
> });
> ```
>
> The `CustomPaywallActionEvent` contains:
>
> * `actionName`: The action identifier from JavaScript
> * `params`: Object of parameters from JavaScript
> * `triggerName`: The trigger that opened this paywall
> * `paywallName`: The paywall template name


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.