Triggers

Define events that initiate paywall presentation

A trigger is a named placement in your app where you want to present a paywall. Think of it as a specific moment or screen in your user journey — like after onboarding, when a user hits a feature gate, or when they open settings.

When the Helium SDK encounters a trigger in your app code, it resolves the trigger to a workflow, which determines which paywall (or A/B experiment) to display.

---

Anatomy of a Trigger

Each trigger has three fields:

Field	Description
Trigger Name	A human-readable label for the trigger (e.g., “Post Onboarding”). Editable after creation.
Trigger Key	A programmatic identifier used in your SDK integration (e.g., post_onboarding). Only letters, numbers, and underscores. Cannot be changed after creation.
Description	An optional note describing when or where this trigger fires.

---

Lifecycle of a Trigger

1. Create

   Triggers can be created in two ways:

   • During onboarding — The “Wire up your paywall” flow creates a trigger, a default workflow, and connects them to your first paywall in one step.
   • From a workflow — On any workflow’s detail page, you can add triggers from the Triggers section. Create new ones inline, or attach existing unassigned triggers.

   When you create a trigger, you choose a trigger key. This is the identifier you’ll use in your app’s code, so pick something descriptive and stable — it can’t be renamed later. The trigger name and description can be updated at any time.

2. Associate with Workflow

   A trigger must be linked to exactly one workflow. A workflow can have many triggers, but each trigger can only belong to a single workflow at a time. This constraint is enforced automatically — if you try to assign a trigger that’s already in use by another workflow, you’ll see an error.

   This means multiple entry points in your app (e.g., feature_gate, settings_upsell, post_onboarding) can all route to the same paywall experience, while each trigger still gets its own analytics.

3. Integrate in Your App

   Once created and associated with a workflow, use the trigger key in your SDK integration:

   // iOS example

   Helium.trigger(“post_onboarding”)

   When this code runs, the SDK sends the trigger key to Helium, which resolves it to the associated workflow and returns the correct paywall (or experiment variant) to display.

4. Analyze

   Triggers appear throughout Helium’s analytics. You can filter and group by trigger to understand how each entry point performs — for example, comparing conversion rates between post_onboarding and feature_gate. Trigger attribution flows through to paywall sessions and subscription data.

5. Edit

   You can update a trigger’s name and description at any time from the trigger’s detail page. The trigger key is immutable — if you need a different key, create a new trigger and reassign it to the workflow.

6. Move or Reassign

   Triggers can be detached from one workflow and attached to another. When you remove a trigger from a workflow, that trigger’s key will immediately stop serving that workflow’s paywalls.

7. Delete

   A trigger can only be deleted if it is not currently associated with any workflow. If it’s in use, you’ll be shown which workflow(s) reference it and prompted to remove the association first. Deletion is permanent.

---

Reserved Trigger Keys

Helium reserves a small set of trigger keys for system-managed workflows:

Key	Purpose
hlm_ios_default_flbk	iOS default fallback workflow
hlm_android_default_flbk	Android default fallback workflow

These cannot be used for custom triggers.

---

Key Rules

• Each trigger belongs to exactly one workflow at a time.
• One workflow can have multiple triggers.
• Trigger keys are unique per organization and immutable after creation.
• Trigger keys can only contain letters, numbers, and underscores.
• A trigger must be unassociated from all workflows before it can be deleted.

---

Common Patterns

Pattern	Example Key	When It Fires
Post-onboarding	post_onboarding	Right after a new user completes onboarding
Feature gate	feature_gate_ai_tools	When a free user taps a premium feature
Settings upsell	settings_upgrade	From an “Upgrade” button on the settings screen
Session-based	session_start_day_3	On app open after the user’s 3rd day