Overview

The Helium SDK fires various events related to paywall display and purchase actions. Visit the SDK docs to see how to listen for and handle these events.

Event Types

iOS
React Native
Flutter

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

// Events with paywall context
protocol PaywallContextEvent: PaywallEvent {
    var triggerName: String { get }
    var paywallName: String { get }
}

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

export type HeliumPaywallEvent = {
  type: 'paywallOpen' | 'paywallClose' | 'paywallDismissed' |
    'paywallOpenFailed' | 'paywallSkipped' | 'paywallButtonPressed' |
    'productSelected' | 'purchasePressed' | 'purchaseSucceeded' |
    'purchaseCancelled' | 'purchaseFailed' | 'purchaseRestored' |
    'purchaseRestoreFailed' | 'purchasePending' | 'initializeStart' |
    'paywallsDownloadSuccess' | 'paywallsDownloadError' | 'paywallWebViewRendered';
  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;
  timestamp?: number; // Unix timestamp in seconds (using device clock)
}

Listening to Events

See the SDK quickstarts for examples on how to listen for events, either through a Helium delegate or by passing in handlers during paywall presentation.

Available Events

The following definitions are all provided in Swift, but the same events and values are available for every SDK.

Lifecycle Events

PaywallOpenEvent

Fires when a paywall is displayed.

let event: PaywallOpenEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.viewType        // .presented, .triggered, or .embedded
event.timestamp       // When event occurred

PaywallCloseEvent

Fires when a paywall is closed (removed from view hierarchy). This might be due to a user dismissal, successful purchase, or programmatic hide.

let event: PaywallCloseEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.timestamp       // When event occurred

PaywallDismissedEvent

Fires when paywall is explicitly dismissed by user.

let event: PaywallDismissedEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.dismissAll      // Whether entire paywall stack dismissed (i.e. second try)
event.timestamp       // When event occurred

PaywallOpenFailedEvent

Fires if a paywall fails to open and fallback fails to show. (This should be extremely rare.)

let event: PaywallOpenFailedEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.error           // Error message describing why paywall failed to open
event.timestamp       // When event occurred

PaywallSkippedEvent

Fires if a paywall display is skipped due to a targeting or workflow configuration.

let event: PaywallSkippedEvent
event.triggerName     // Associated trigger
event.timestamp       // When event occurred

PaywallButtonPressedEvent

Fires when a non-purchase button is pressed.

let event: PaywallButtonPressedEvent
event.buttonName      // Button identifier
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.timestamp       // When event occurred

PaywallWebViewRenderedEvent

Fires when the paywall content has finished rendering.

let event: PaywallWebViewRenderedEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.isSecondTry     // True if paywall is "second try" flow
event.renderTime      // Time to render (ms)
event.timestamp       // When event occurred

Purchase Events

ProductSelectedEvent

Fires when a user selects a product on the paywall.

let event: ProductSelectedEvent
event.productId       // StoreKit product ID
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchasePressedEvent

Fires when a purchase is initiated.

let event: PurchasePressedEvent
event.productId       // Product being purchased
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchaseSucceededEvent

Fires when a purchase is successfully completed.

let event: PurchaseSucceededEvent
event.productId       // StoreKit product ID
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchaseCancelledEvent

Fires when the purchase process is cancelled by the user.

let event: PurchaseCancelledEvent
event.productId       // Product that was cancelled
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchaseFailedEvent

Fires when the process fails for any reason.

let event: PurchaseFailedEvent
event.productId       // Product that failed
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.error           // StoreKit error object
event.timestamp       // When event occurred

PurchaseRestoredEvent

Fires when a previous purchase is successfully restored.

let event: PurchaseRestoredEvent
event.productId       // Restored product ID
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchaseRestoreFailedEvent

Fires when an attempt to restore purchases is not successful.

let event: PurchaseRestoreFailedEvent
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

PurchasePendingEvent

Fires when when purchase is in a pending state (e.g. waiting for parental approval).

let event: PurchasePendingEvent
event.productId       // Pending product
event.triggerName     // Associated trigger
event.paywallName     // Template name
event.timestamp       // When event occurred

System Events

InitializeStartEvent

Fires when SDK initialization is started.

let event: InitializeStartEvent
event.timestamp       // When event occurred

PaywallsDownloadSuccessEvent

Fires when Helium paywalls downloaded and initialized successfully.

let event: PaywallsDownloadSuccessEvent
event.downloadTime    // Total download time (ms)
event.numAttempts     // Number of attempts made
event.timestamp       // When event occurred

PaywallsDownloadErrorEvent

Fires when paywalls download failed.

let event: PaywallsDownloadErrorEvent
event.error           // Error description
event.numAttempts     // Attempts made
event.timestamp       // When event occurred

Legacy Events

The following section documents the legacy event system from SDK versions lower than 3.x. For new implementations, use the event system described above.

Legacy Event Handling

The legacy system uses the onHeliumPaywallEvent method with an enum-based approach:

func onHeliumPaywallEvent(event: HeliumPaywallEvent) {
    switch (event) {
    case .paywallOpen(let triggerName, let paywallTemplateName, let viewType):
        print("Paywall opened: \(triggerName), template: \(paywallTemplateName), viewType: \(viewType)")
    case .subscriptionSucceeded(let productKey, let triggerName, let paywallTemplateName):
        print("Subscription succeeded for product: \(productKey)")
    // Handle other events as needed
    default:
        break
    }
}

Initialization Events

Initialize Start

case initializeStart

Triggered when the Helium SDK initialization process begins.

User Interaction Events

CTA Pressed

case ctaPressed(ctaName: String, triggerName: String, paywallTemplateName: String)

Triggered when a user presses a Call-To-Action (CTA) button on the paywall.

Offer Selected

case offerSelected(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a user selects a specific offer or product.

Subscription Pressed

case subscriptionPressed(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a user presses the subscribe button for a specific product.

Subscription Status Events

Subscription Cancelled

case subscriptionCancelled(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a subscription process is cancelled by the user.

Subscription Succeeded

case subscriptionSucceeded(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a subscription is successfully completed.

Subscription Failed

case subscriptionFailed(productKey: String, triggerName: String, paywallTemplateName: String, error: String? = nil)

Triggered when the subscription process fails for any reason.

Subscription Restored

case subscriptionRestored(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a previous subscription is successfully restored.

Subscription Restore Failed

case subscriptionRestoreFailed(triggerName: String, paywallTemplateName: String)

Triggered when an attempt to restore purchases fails.

Subscription Pending

case subscriptionPending(productKey: String, triggerName: String, paywallTemplateName: String)

Triggered when a subscription is in a pending state (e.g., waiting for approval).

Paywall Lifecycle Events

Paywall Open

case paywallOpen(triggerName: String, paywallTemplateName: String, viewType: String)

Triggered when a paywall is successfully opened and displayed to the user. View type maps to:

public enum PaywallOpenViewType : String {
    case presented = "presented" // via presentUpsell
    case triggered = "triggered" // shown via SwiftUI view modifier
    case embedded = "embedded" // paywall was manually embedded
}

Paywall Open Failed

case paywallOpenFailed(triggerName: String, paywallTemplateName: String)

Triggered when there’s an error opening or displaying the paywall.

Paywall Close

case paywallClose(triggerName: String, paywallTemplateName: String)

Triggered when the paywall is closed programmatically.

Paywall Dismissed

case paywallDismissed(triggerName: String, paywallTemplateName: String, dismissAll: Bool = false)

Triggered when the user dismisses the paywall.

Paywall Skipped

case paywallSkipped(triggerName: String)

Triggered when a paywall open gets skipped for a trigger, due to a targeting or workflow configuration.

Paywall WebView Rendered

case paywallWebViewRendered(triggerName: String, paywallTemplateName: String, webviewRenderTimeTakenMS: UInt64? = nil)

Triggered when a WebView-based paywall has been successfully rendered.

Configuration Events

Paywalls Download Success

case paywallsDownloadSuccess(configId: UUID, downloadTimeTakenMS: UInt64? = nil, imagesDownloadTimeTakenMS: UInt64? = nil, fontsDownloadTimeTakenMS: UInt64? = nil, bundleDownloadTimeMS: UInt64? = nil, numAttempts: Int? = nil)

Triggered when paywall configurations are successfully downloaded.

Paywalls Download Error

case paywallsDownloadError(error: String, numAttempts: Int? = nil)

Triggered when there’s an error downloading paywall configurations.

​Overview

​Event Types

​Listening to Events

​Available Events

​Lifecycle Events

​PaywallOpenEvent

​PaywallCloseEvent

​PaywallDismissedEvent

​PaywallOpenFailedEvent

​PaywallSkippedEvent

​PaywallButtonPressedEvent

​PaywallWebViewRenderedEvent

​Purchase Events

​ProductSelectedEvent

​PurchasePressedEvent

​PurchaseSucceededEvent

​PurchaseCancelledEvent

​PurchaseFailedEvent

​PurchaseRestoredEvent

​PurchaseRestoreFailedEvent

​PurchasePendingEvent

​System Events

​InitializeStartEvent

​PaywallsDownloadSuccessEvent

​PaywallsDownloadErrorEvent

​Legacy Events

​Legacy Event Handling

​Initialization Events

​Initialize Start

​User Interaction Events

​CTA Pressed

​Offer Selected

​Subscription Pressed

​Subscription Status Events

​Subscription Cancelled

​Subscription Succeeded

​Subscription Failed

​Subscription Restored

​Subscription Restore Failed

​Subscription Pending

​Paywall Lifecycle Events

​Paywall Open

​Paywall Open Failed

​Paywall Close

​Paywall Dismissed

​Paywall Skipped

​Paywall WebView Rendered

​Configuration Events

​Paywalls Download Success

​Paywalls Download Error

Overview

Event Types

Listening to Events

Available Events

Lifecycle Events

PaywallOpenEvent

PaywallCloseEvent

PaywallDismissedEvent

PaywallOpenFailedEvent

PaywallSkippedEvent

PaywallButtonPressedEvent

PaywallWebViewRenderedEvent

Purchase Events

ProductSelectedEvent

PurchasePressedEvent

PurchaseSucceededEvent

PurchaseCancelledEvent

PurchaseFailedEvent

PurchaseRestoredEvent

PurchaseRestoreFailedEvent

PurchasePendingEvent

System Events

InitializeStartEvent

PaywallsDownloadSuccessEvent

PaywallsDownloadErrorEvent

Legacy Events

Legacy Event Handling

Initialization Events

Initialize Start

User Interaction Events

CTA Pressed

Offer Selected

Subscription Pressed

Subscription Status Events

Subscription Cancelled

Subscription Succeeded

Subscription Failed

Subscription Restored

Subscription Restore Failed

Subscription Pending

Paywall Lifecycle Events

Paywall Open

Paywall Open Failed

Paywall Close

Paywall Dismissed

Paywall Skipped

Paywall WebView Rendered

Configuration Events

Paywalls Download Success

Paywalls Download Error