> ## Documentation Index
> Fetch the complete documentation index at: https://helium-mintlify-create-navigation-structure-42614.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

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