Helium Events

Overview

Helium emits paywall and lifecycle events related to paywalls, purchasing, configuration, and experimentation. This page acts as a reference to what events are available in Helium, and when each one is fired. Visit each SDK’s quickstart page to see how to listen for and handle events.

Event Types

iOS
Android
React Native
Flutter

// Base protocol for all events
protocol HeliumEvent {
    var eventName: String { get }
    var timestamp: Date { get }
    func toDictionary() -> [String: Any]
}

// Events with paywall context
protocol PaywallContextEvent: HeliumEvent {
    var triggerName: String { get }
    var paywallName: String { get }
    var isSecondTry: Bool { get }
}

// Product-related events
protocol ProductEvent: PaywallContextEvent {
    var productId: String { get }
}

// All Event Types:
// Lifecycle: PaywallOpenEvent, PaywallCloseEvent, PaywallDismissedEvent,
//            PaywallSkippedEvent, PaywallButtonPressedEvent
// Purchase:  ProductSelectedEvent, PurchasePressedEvent, PurchaseSucceededEvent,
//            PurchaseCancelledEvent, PurchaseFailedEvent, PurchaseRestoredEvent,
//            PurchaseRestoreFailedEvent, PurchasePendingEvent
// System:    InitializeStartEvent, PaywallsDownloadSuccessEvent,
//            PaywallsDownloadErrorEvent, PaywallWebViewRenderedEvent
// Experiment: UserAllocatedEvent

// Base sealed class for all events
sealed class HeliumEvent(
    open val timestamp: Long
)

// Events with paywall context
sealed class PaywallContextEvent(
    override val timestamp: Long,
    open val triggerName: String,
    open val paywallName: String,
    open val isSecondTry: Boolean,
) : HeliumEvent(timestamp)

// Product-related events
sealed class ProductEvent(
    override val timestamp: Long,
    override val triggerName: String,
    override val paywallName: String,
    override val isSecondTry: Boolean,
    open val productId: String,
) : PaywallContextEvent(timestamp, triggerName, paywallName, isSecondTry)

// All Event Classes:
// Lifecycle: PaywallOpen, PaywallClose, PaywallDismissed, PaywallOpenFailed,
//            PaywallSkipped, PaywallButtonPressed
// Purchase:  ProductSelected, PurchasedPressed, PurchaseSucceeded, PurchaseCancelled,
//            PurchaseFailed, PurchaseRestored, PurchaseRestoreFailed, PurchasePending
// System:    InitializeStart, InitializeCalled, PaywallsDownloadSuccess,
//            PaywallsDownloadError, PaywallWebViewRendered

export type HeliumPaywallEvent = {
  type: 'paywallOpen' | 'paywallClose' | 'paywallDismissed' |
    'paywallOpenFailed' | 'paywallSkipped' | 'paywallButtonPressed' |
    'productSelected' | 'purchasePressed' | 'purchaseSucceeded' |
    'purchaseCancelled' | 'purchaseFailed' | 'purchaseRestored' |
    'purchaseRestoreFailed' | 'purchasePending' | 'initializeStart' |
    'paywallsDownloadSuccess' | 'paywallsDownloadError' | 
    'paywallWebViewRendered' | 'userAllocated';
  triggerName?: string;
  paywallName?: string;
  productId?: string;
  buttonName?: string;
  configId?: string;
  numAttempts?: number;
  downloadTimeTakenMS?: number;
  webviewRenderTimeTakenMS?: number;
  imagesDownloadTimeTakenMS?: number;
  fontsDownloadTimeTakenMS?: number;
  bundleDownloadTimeMS?: number;
  dismissAll?: boolean;
  isSecondTry?: boolean;
  error?: string;
  experimentInfo?: ExperimentInfo;
  timestamp?: number;
}

// Base event structure
abstract class HeliumEvent {
  String get eventName;
  DateTime get timestamp;
  Map<String, dynamic> toMap();
}

// Events with paywall context
abstract class PaywallContextEvent extends HeliumEvent {
  String get triggerName;
  String get paywallName;
  bool get isSecondTry;
}

// Product-related events
abstract class ProductEvent extends PaywallContextEvent {
  String get productId;
}

// All Event Types:
// Lifecycle: PaywallOpenEvent, PaywallCloseEvent, PaywallDismissedEvent,
//            PaywallOpenFailedEvent, PaywallSkippedEvent, PaywallButtonPressedEvent
// Purchase:  ProductSelectedEvent, PurchasePressedEvent, PurchaseSucceededEvent,
//            PurchaseCancelledEvent, PurchaseFailedEvent, PurchaseRestoredEvent,
//            PurchaseRestoreFailedEvent, PurchasePendingEvent
// System:    InitializeStartEvent, PaywallsDownloadSuccessEvent,
//            PaywallsDownloadErrorEvent, PaywallWebViewRenderedEvent

Available Events

Paywall and Purchase Events

Event Name	Description	Parameters
paywallOpen	Fires when a paywall is displayed	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `viewType` (String) - presented, triggered, or embedded `loadTimeTakenMS` (Number, optional) - Loading time in milliseconds `loadingBudgetMS` (Number, optional) - Loading budget in milliseconds `timestamp` (Number) - When event occurred
paywallClose	Fires when a paywall is closed (removed from view hierarchy). Fires on both explicit dismissal AND purchase success	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
paywallDismissed	Fires when paywall is explicitly dismissed by user	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `dismissAll` (Boolean) - Whether entire paywall stack dismissed `timestamp` (Number) - When event occurred
paywallSkipped	Fires if paywall display is skipped due to targeting or workflow configuration	`triggerName` (String) - Associated trigger `timestamp` (Number) - When event occurred
paywallButtonPressed	Fires when a non-purchase button is pressed	`buttonName` (String) - Button identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
paywallWebViewRendered	Fires when the paywall content has finished rendering	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `webviewRenderTimeTakenMS` (Number, optional) - Time to render in milliseconds `timestamp` (Number) - When event occurred
productSelected	Fires when a user selects a product on the paywall	`productId` (String) - Product identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
purchasePressed	Fires when a purchase button is pressed in the paywall	`productId` (String) - Product being purchased `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
purchaseSucceeded	Fires when a purchase is successfully completed.	`productId` (String) - Product identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `storeKitTransactionId` (String, optional) - Transaction ID `storeKitOriginalTransactionId` (String, optional) - Original transaction ID `skPostPurchaseTxnTimeMS` (Number, optional) - Post-purchase transaction time `timestamp` (Number) - When event occurred
purchaseCancelled	Fires when the purchase process is cancelled by the user	`productId` (String) - Product that was cancelled `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
purchaseFailed	Fires when the purchase fails for any reason	`productId` (String) - Product that failed `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `error` (String, optional) - Error message `timestamp` (Number) - When event occurred
purchaseRestored	Fires when a previous purchase is successfully restored	`productId` (String) - Restored product ID `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
purchaseRestoreFailed	Fires when an attempt to restore purchases fails	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred
purchasePending	Fires when purchase is in a pending state (e.g. waiting for parental approval)	`productId` (String) - Pending product `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `timestamp` (Number) - When event occurred

System Events

Event Name	Description	Parameters
initializeStart	Fires when SDK initialization is started	`timestamp` (Number) - When event occurred
paywallsDownloadSuccess	Fires when Helium paywalls downloaded and initialized successfully	`downloadTimeTakenMS` (Number, optional) - Config download time in milliseconds `imagesDownloadTimeTakenMS` (Number, optional) - Images download time in milliseconds `fontsDownloadTimeTakenMS` (Number, optional) - Fonts download time in milliseconds `bundleDownloadTimeMS` (Number, optional) - Bundle download time in milliseconds `numAttempts` (Number, optional) - Number of attempts made `timestamp` (Number) - When event occurred
paywallsDownloadError	Fires when paywalls download failed	`error` (String) - Error description `numAttempts` (Number, optional) - Number of attempts made `timestamp` (Number) - When event occurred
paywallOpenFailed	Fires if a paywall fails to open and fallback fails to show	`triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is “second try” flow `error` (String) - Error message describing failure `timestamp` (Number) - When event occurred

Experiment Events

Event Name	Description	Parameters
userAllocated	Fires once per trigger when a user is allocated to an experiment variant	`experimentInfo` (Object) - Complete experiment allocation data (see below) `timestamp` (Number) - When allocation occurred

ExperimentInfo Structure

The experimentInfo object in the userAllocated event contains experiment allocation data. This event fires once per session when a user is assigned to an experiment variant, which happens on the first trigger the user sees.

Core Fields

Field	Type	Description
`trigger`	String	Name of the first trigger the user sees

Experiment Details

Field	Type	Description
`experimentName`	String	Human-readable name of the experiment
`experimentId`	String	Unique identifier for the experiment. You can look this experiment id up in the helium dashboard
`experimentType`	String	Type of experiment (e.g., “A/B/n test”, “MAB”, “CMAB”)
`startDate`	DateTime	When the experiment started
`endDate`	DateTime	When the experiment ends

Targeting Details

Field	Type	Description
`audienceId`	String	Audience ID that user matched (for lookup in Helium)
`audienceDataDictionary`	Object	Parsed audience rules/criteria - `operator`: How rules are combined (“AND”, “OR”) - `isAllUsers`: Whether this targets all users - `rules`: Array of targeting rules that matched

Variant Details

Field	Type	Description
`chosenVariantIndex`	Integer	Variant number (1-indexed)
`chosenVariantDetails`	Object	Details about the assigned variant
`chosenVariantDetails.allocationName`	String	Variant/paywall name
`chosenVariantDetails.allocationId`	String	Variant UUID
`chosenVariantDetails.allocationTime`	DateTime	When the user was allocated to this variant

Hash Details

These fields provide information about how the user was deterministically assigned to a variant.

Field	Type	Description
`hashedUserIdBucket1To100`	Integer	User’s hash bucket (1-100) - deterministic value for consistent variant assignment
`hashedUserId`	String	The user ID that was hashed
`hashMethod`	String	Hash method used: - `"HASH_USER_ID"`: Standard user ID hashing - `"HASH_HELIUM_PERSISTENT_ID"`: Persistent device ID hashing (more stable across reinstalls)

Logged Events

All Helium events (see the full list above) get logged to your analytics backend automatically with automatic event forwarding, along with the parameters listed there. Each event’s parameters will usually show up as event properties.

Event names and properties might show up as underscored/camelcase/JSON, depending on the platform.

In addition, all lifecycle, paywall, downloadSuccess, and experimental events will include contextual and custom traits as event parameters:

Contextual Traits

Helium automatically and securely collects device and software attributes:

Locale: country, currency, currency symbol, language, preferred languages, time zone, decimal separator, uses metric system
Screen: brightness, bounds, native bounds, scale, native scale, dark mode enabled
Device: device identifier, orientation, system name, system version, device model, interface idiom, storage capacity
Application: version, build number, app name, Helium SDK version, environment

Custom Traits

Custom user traits included in the Helium.initialize() call also get sent as part of all events. If you pass custom user traits as part of a paywall presentation method call, these will override any custom traits of the same name passed in during initialize().

Getting Started

SDK Quickstarts

Guides

SDK Reference

Overview

Event Types

Available Events

Paywall and Purchase Events

System Events

Experiment Events

ExperimentInfo Structure

Core Fields

Experiment Details

Targeting Details

Variant Details

Hash Details

Logged Events

Contextual Traits

Custom Traits

​Overview

​Event Types

​Available Events

​Paywall and Purchase Events

​System Events

​Experiment Events

​ExperimentInfo Structure

​Core Fields

​Experiment Details

​Targeting Details

​Variant Details

​Hash Details

​Logged Events

​Contextual Traits

​Custom Traits

Overview

Event Types

Available Events

Paywall and Purchase Events

System Events

Experiment Events

ExperimentInfo Structure

Core Fields

Experiment Details

Targeting Details

Variant Details

Hash Details

Logged Events

Contextual Traits

Custom Traits