​

Helium Events

Helium SDK emits various events during the lifecycle of paywalls and user interactions. These events can be used for analytics, debugging, and optimizing your paywall strategy.

​

Handling Events

You can listen to these events by implementing the onHeliumPaywallEvent method in your HeliumPaywallDelegate:

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

​

Event Categories

Helium events are organized into the following categories:

​

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.

• ctaName: The name or identifier of the CTA button pressed.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Offer Selected

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

Triggered when a user selects a specific offer or product.

• productKey: The key or identifier of the selected product or offer.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Pressed

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

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

• productKey: The key or identifier of the product being subscribed to.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Status Events

​

Subscription Cancelled

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

Triggered when a subscription process is cancelled by the user.

• productKey: The key or identifier of the product.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Succeeded

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

Triggered when a subscription is successfully completed.

• productKey: The key or identifier of the product.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Failed

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

Triggered when the subscription process fails for any reason.

• productKey: The key or identifier of the product.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.
• error: Optional string describing the error that occurred during the subscription process.

​

Subscription Restored

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

Triggered when a previous subscription is successfully restored.

• productKey: The key or identifier of the product (if available otherwise “HELIUM_GENERIC_PRODUCT”).
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Restore Failed

subscriptionRestoreFailed(triggerName: String, paywallTemplateName: String)

Triggered when an attempt to restore purchases fails.

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Subscription Pending

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

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

• productKey: The key or identifier of the product.
• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

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.

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.
• viewType: How the paywall was displayed. It maps to this enum:

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.

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Paywall Close

case paywallClose(triggerName: String, paywallTemplateName: String)

Triggered when the paywall is closed programmatically.

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.

​

Paywall Dismissed

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

Triggered when the user dismisses the paywall.

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.
• dismissAll: Whether this dismiss action should dismiss ALL visible paywalls (i.e. secondary and primary paywalls). Typically after a successful purchase.

​

Paywall Skipped

case paywallSkipped(triggerName: String)

Triggered when the paywall was not shown. e.g. if “Don’t Show Paywall” was set in the dashboard targeting.

• triggerName: The name of the trigger that initiated the paywall.

​

Paywall WebView Rendered

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

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

• triggerName: The name of the trigger that initiated the paywall.
• paywallTemplateName: The name of the paywall template being used.
• webviewRenderTimeTakenMS: Optional time in milliseconds that it took to render the WebView.

​

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.

• configId: The unique identifier of the downloaded configuration.
• downloadTimeTakenMS: Optional time in milliseconds that it took to download the configuration.
• imagesDownloadTimeTakenMS: Optional time in milliseconds that it took to download images.
• fontsDownloadTimeTakenMS: Optional time in milliseconds that it took to download fonts.
• bundleDownloadTimeMS: Optional time in milliseconds that it took to download bundles.
• numAttempts: How many attempts it took to successfully download.

​

Paywalls Download Error

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

Triggered when there’s an error downloading paywall configurations.

• error: A string describing the error that occurred during download.
• numAttempts: How many attempts were made.

​

Using Events for Analytics

Helium events can be integrated with your existing analytics systems. Here’s an example of how you might forward Helium events to your analytics service:

func onHeliumPaywallEvent(event: HeliumPaywallEvent) {
    // Convert the event to a dictionary
    let eventDict = event.toDictionary()
    
    // Log to your analytics service
    switch event {
    case .subscriptionSucceeded:
        YourAnalyticsService.track(event: "Subscription Completed", properties: eventDict)
    case .paywallOpen:
        YourAnalyticsService.track(event: "Paywall Viewed", properties: eventDict)
    // Add more cases as needed
    default:
        YourAnalyticsService.track(event: "Helium Event: \(event.caseString())", properties: eventDict)
    }
    
    // You can also implement custom business logic based on events
    if case .subscriptionSucceeded = event {
        // Update user properties, unlock premium features, etc.
    }
}

​

Performance Monitoring

Several Helium events include timing information that can be used to monitor the performance of your paywalls:

• paywallsDownloadSuccess includes download times for configurations, images, fonts, and bundles
• paywallWebViewRendered includes the time taken to render WebView-based paywalls

You can use this data to identify potential performance issues and optimize the user experience.