> ## Documentation Index
> Fetch the complete documentation index at: https://helium-promptless-document-entitlement-management-features.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Helium Events

> Understanding Helium SDK Events

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

<Tabs>
  <Tab title="iOS">
    ```swift
    // 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 }
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript
    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)
    }
    ```
  </Tab>

  <Tab title="Flutter">
    New events coming soon! For now look at the Legacy Events section.
  </Tab>
</Tabs>

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

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

### Lifecycle Events

#### PaywallOpenEvent

Fires when a paywall is displayed.

```swift
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.

```swift
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.

```swift
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.)

```swift
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.

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

#### PaywallButtonPressedEvent

Fires when a non-purchase button is pressed.

```swift
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.

```swift
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.

```swift
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.

```swift
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.

```swift
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.

```swift
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.

```swift
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.

```swift
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.

```swift
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).

```swift
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.

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

#### PaywallsDownloadSuccessEvent

Fires when Helium paywalls downloaded and initialized successfully.

```swift
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.

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

***

# Legacy Events

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

### Legacy Event Handling

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

```swift
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

```swift
case initializeStart
```

Triggered when the Helium SDK initialization process begins.

### User Interaction Events

#### CTA Pressed

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

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

#### Offer Selected

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

Triggered when a user selects a specific offer or product.

#### Subscription Pressed

```swift
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

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

Triggered when a subscription process is cancelled by the user.

#### Subscription Succeeded

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

Triggered when a subscription is successfully completed.

#### Subscription Failed

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

Triggered when the subscription process fails for any reason.

#### Subscription Restored

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

Triggered when a previous subscription is successfully restored.

#### Subscription Restore Failed

```swift
case subscriptionRestoreFailed(triggerName: String, paywallTemplateName: String)
```

Triggered when an attempt to restore purchases fails.

#### Subscription Pending

```swift
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

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

Triggered when a paywall is successfully opened and displayed to the user.

View type maps to:

```swift
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

```swift
case paywallOpenFailed(triggerName: String, paywallTemplateName: String)
```

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

#### Paywall Close

```swift
case paywallClose(triggerName: String, paywallTemplateName: String)
```

Triggered when the paywall is closed programmatically.

#### Paywall Dismissed

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

Triggered when the user dismisses the paywall.

#### Paywall Skipped

```swift
case paywallSkipped(triggerName: String)
```

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

#### Paywall WebView Rendered

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

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

### Configuration Events

#### Paywalls Download Success

```swift
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

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

Triggered when there's an error downloading paywall configurations.