SuperwallEvent

An enum representing analytical events that are automatically tracked by Superwall.

These events provide comprehensive analytics about user behavior and paywall performance. Use them to track conversion funnels, user engagement, and revenue metrics in your analytics platform.

Common events to track for conversion analysis include triggerFire, paywallOpen, transactionStart, and transactionComplete.

Purpose

Represents internal analytics events tracked by Superwall and sent to the SuperwallDelegate for forwarding to your analytics platform.

Signature

public enum SuperwallEvent {
  // User lifecycle events
  case firstSeen
  case appOpen
  case appLaunch
  case appClose
  case sessionStart
  case identityAlias
  case appInstall
  
  // Deep linking
  case deepLink(url: URL)
  
  // Paywall events
  case triggerFire(placementName: String, result: TriggerResult)
  case paywallOpen(paywallInfo: PaywallInfo)
  case paywallClose(paywallInfo: PaywallInfo)
  case paywallDecline(paywallInfo: PaywallInfo)
  case paywallWebviewProcessTerminated(paywallInfo: PaywallInfo)
  case paywallPreloadStart(paywallCount: Int)
  case paywallPreloadComplete(paywallCount: Int)
  case stripeCheckoutStart(paywallInfo: PaywallInfo)
  case stripeCheckoutSubmit(paywallInfo: PaywallInfo)
  case stripeCheckoutComplete(paywallInfo: PaywallInfo)
  case stripeCheckoutFail(paywallInfo: PaywallInfo)
  case testModeModalOpen
  case testModeModalClose
  
  // Transaction events
  case transactionStart(product: StoreProduct, paywallInfo: PaywallInfo)
  case transactionComplete(transaction: StoreTransaction?, product: StoreProduct, type: TransactionType, paywallInfo: PaywallInfo)
  case transactionFail(error: TransactionError, paywallInfo: PaywallInfo)
  case transactionAbandon(product: StoreProduct, paywallInfo: PaywallInfo)
  case transactionRestore(restoreType: RestoreType, paywallInfo: PaywallInfo)
  case transactionTimeout(paywallInfo: PaywallInfo)
  
  // Subscription events
  case subscriptionStart(product: StoreProduct, paywallInfo: PaywallInfo)
  case freeTrialStart(product: StoreProduct, paywallInfo: PaywallInfo)
  case subscriptionStatusDidChange
  
  // System events
  case deviceAttributes(attributes: [String: Any])
  case reviewRequested(count: Int)

  // Permission events (Request permission action)
  case permissionRequested(permissionName: String, paywallIdentifier: String)
  case permissionGranted(permissionName: String, paywallIdentifier: String)
  case permissionDenied(permissionName: String, paywallIdentifier: String)
  
  // And more...
}

Parameters

Each event case contains associated values with relevant information for that event type. Common parameters include:

paywallInfo: PaywallInfo - Information about the paywall
product: StoreProduct - The product involved in transactions
url: URL - Deep link URLs
attributes: [String: Any] - Device or user attributes
count: Int - For reviewRequested, the number of times a review has been requested (available in version 4.8.1+)
permissionName: String / paywallIdentifier: String - The permission requested from the paywall and the identifier of the paywall that triggered it (new in 4.12.0).
paywallCount: Int - Total number of paywalls being preloaded when paywallPreloadStart/paywallPreloadComplete fire (new in 4.12.0).

Returns / State

This is an enum that represents different event types. Events are received via SuperwallDelegate.handleSuperwallEvent(withInfo:).

Usage

These events are received via SuperwallDelegate.handleSuperwallEvent(withInfo:) for forwarding to your analytics platform.

The Request permission action for the paywall editor is rolling out and isn't visible in the dashboard yet. Editor support is coming very soon, so you may not see the action in your workspace today.

When you wire the Request permission action in the paywall editor, the SDK emits permission_requested, permission_granted, and permission_denied events. Use them to track opt-in funnels or adapt your UI:

func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
  switch eventInfo.event {
  case .permissionRequested(let permission, let paywallId):
    logger.info("Prompting \(permission) from paywall \(paywallId)")
  case .permissionGranted(let permission, _):
    analytics.track("permission_granted", properties: eventInfo.params)
  case .permissionDenied(let permission, _):
    showSettingsNudge(for: permission)
  default:
    break
  }
}

See the Request permissions from paywalls guide for setup details and Info.plist requirements.

Paywall preloading events (4.12.0+)

paywallPreload_start and paywallPreload_complete fire whenever the SDK preloads cached paywalls in the background. Both events include paywall_count inside eventInfo.params, and the enum cases expose the same value via paywallCount. This makes it easy to time or monitor cache warm-up:

switch eventInfo.event {
case .paywallPreloadStart(let count):
  Metrics.shared.begin("paywall_preload", metadata: ["count": count])
case .paywallPreloadComplete(let count):
  Metrics.shared.end("paywall_preload", metadata: ["count": count])
default:
  break
}

Pair these events with the shouldPreload option if you want to compare “on-demand” versus background caching strategies.

Stripe checkout events (4.14.0+)

When users go through web checkout with Stripe, the SDK emits four lifecycle events that you can forward to analytics:

stripeCheckoutStart
stripeCheckoutSubmit
stripeCheckoutComplete
stripeCheckoutFail

These events include paywall context and are useful for monitoring checkout funnel progression.

switch eventInfo.event {
case .stripeCheckoutStart:
  analytics.track("stripe_checkout_start", properties: eventInfo.params)
case .stripeCheckoutSubmit:
  analytics.track("stripe_checkout_submit", properties: eventInfo.params)
case .stripeCheckoutComplete:
  analytics.track("stripe_checkout_complete", properties: eventInfo.params)
case .stripeCheckoutFail:
  analytics.track("stripe_checkout_fail", properties: eventInfo.params)
default:
  break
}

Test mode events (4.14.0+)

When Test Mode is enabled, the SDK emits events for the modal lifecycle:

testModeModalOpen
testModeModalClose

Use these events to understand when testers are entering and exiting test mode flows.

switch eventInfo.event {
case .testModeModalOpen:
  logger.info("Test mode modal opened")
case .testModeModalClose:
  logger.info("Test mode modal closed")
default:
  break
}