SDK Quickstart (iOS)

Helium.shared.initialize(
    apiKey: "helium-api-key"
)

import Helium

Helium.identify.userId = "custom-user-id"

Helium.identify.revenueCatAppUserId = Purchases.shared.appUserID

if let appAccountTokenUUID = UUID(uuidString: "app-account-token-uuid") {
    Helium.identify.appAccountToken = appAccountTokenUUID
}

Helium.identify.setUserTraits(HeliumUserTraits(["hasOnboarded": true]))
// or Helium.identify.addUserTraits() if you don't want to clear existing traits

Helium.shared.presentPaywall(
    trigger: "premium"
) { paywallNotShownReason in
    switch paywallNotShownReason {
        case .targetingHoldout:
            break
        case .alreadyEntitled:
            // e.g. ensure premium access
            // In order for this case to be hit, `config.dontShowIfAlreadyEntitled` must be true
            break
        default:
			// handle the rare case where a paywall
            // fails to show (see Fallbacks section on this page)
            break
    }
}

Helium.shared.presentPaywall(
    trigger: "post_onboarding",
    eventHandlers: PaywallEventHandlers()
        .onOpen { event in
            print("open via trigger \(event.triggerName)")
        }
        .onClose { event in
            print("close for trigger \(event.triggerName)")
        }
        .onDismissed { event in
            print("dismiss for trigger \(event.triggerName)")
        }
        .onPurchaseSucceeded { event in
            print("purchase succeeded for trigger \(event.triggerName)")
        }
        .onCustomPaywallAction { event in
            print("Custom action: \(event.actionName) with params: \(event.params)")
        }
        .onAnyEvent { event in
            // A handler for all paywall-related events.
            // Note that if you have other handlers (i.e. onOpen) set up,
            // both that handler AND this one will fire during paywall open.
        }
) { paywallNotShownReason in
    // handle paywall not shown
}

/// Implement this where you want to handle events
public protocol HeliumEventListener : AnyObject {
    func onHeliumEvent(event: HeliumEvent)
}

/// Add a listener for all Helium events.
public func addHeliumEventListener(_ listener: HeliumEventListener)

/// Remove a specific Helium event listener.
public func removeHeliumEventListener(_ listener: HeliumEventListener)

// ❌ Wrong - listener is deallocated immediately, no events will fire
Helium.shared.addHeliumEventListener(MyListener())

// ✅ Works - singleton keeps a strong reference
class MyHeliumEventListener: HeliumEventListener {
    static let shared = MyHeliumEventListener()

    func onHeliumEvent(event: any HeliumEvent) {
        print("Helium event: \(event.toDictionary())")
    }
}

// And make sure to register it:
Helium.shared.addHeliumEventListener(MyHeliumEventListener.shared)

Helium.config.defaultLoadingBudget = 5
Helium.config.defaultLoadingView = Text("Loading...")