SuperwallEvent

A sealed class 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

import com.superwall.sdk.customercenter.CustomerCenterRefundStatus
import com.superwall.sdk.customercenter.CustomerCenterScreenType

sealed class SuperwallEvent {
    // User lifecycle events
    object FirstSeen : SuperwallEvent()
    object AppOpen : SuperwallEvent()
    object AppLaunch : SuperwallEvent()
    object AppClose : SuperwallEvent()
    object SessionStart : SuperwallEvent()
    object IdentityAlias : SuperwallEvent()
    object AppInstall : SuperwallEvent()

    // Deep linking
    data class DeepLink(val url: String) : SuperwallEvent()

    // Paywall events
    data class TriggerFire(
        val placementName: String,
        val result: TriggerResult
    ) : SuperwallEvent()

    data class PaywallOpen(val paywallInfo: PaywallInfo) : SuperwallEvent()
    data class PaywallPageView(
        val paywallInfo: PaywallInfo,
        val data: PageViewData
    ) : SuperwallEvent()
    data class PaywallClose(val paywallInfo: PaywallInfo) : SuperwallEvent()
    data class PaywallDecline(val paywallInfo: PaywallInfo) : SuperwallEvent()

    // Transaction events
    data class TransactionStart(
        val product: StoreProduct,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class TransactionComplete(
        val transaction: StoreTransaction?,
        val product: StoreProduct,
        val type: TransactionType,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class TransactionFail(
        val error: TransactionError,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class TransactionAbandon(
        val product: StoreProduct,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class TransactionRestore(
        val restoreType: RestoreType,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class TransactionTimeout(val paywallInfo: PaywallInfo) : SuperwallEvent()

    // Subscription events
    data class SubscriptionStart(
        val product: StoreProduct,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    data class FreeTrialStart(
        val product: StoreProduct,
        val paywallInfo: PaywallInfo
    ) : SuperwallEvent()

    object SubscriptionStatusDidChange : SuperwallEvent()

    // Restore events
    sealed class Restore : SuperwallEvent() {
        object Start : Restore()
        data class Fail(val error: String) : Restore()
        object Complete : Restore()
    }

    // Customer and permission events
    data class CustomerInfoDidChange(
        val from: CustomerInfo,
        val to: CustomerInfo
    ) : SuperwallEvent()
    data class PermissionRequested(
        val permissionName: String,
        val paywallIdentifier: String
    ) : SuperwallEvent()
    data class PermissionGranted(
        val permissionName: String,
        val paywallIdentifier: String
    ) : SuperwallEvent()
    data class PermissionDenied(
        val permissionName: String,
        val paywallIdentifier: String
    ) : SuperwallEvent()

    // Preloading events
    data class PaywallPreloadStart(val paywallIdentifier: String) : SuperwallEvent()
    data class PaywallPreloadComplete(val paywallCount: Int) : SuperwallEvent()

    // Test mode events
    class TestModeModalOpen : SuperwallEvent()
    class TestModeModalClose : SuperwallEvent()

    // Customer Center events (2.8.5+)
    data class CustomerCenterOpen(val screen: CustomerCenterScreenType) : SuperwallEvent()
    class CustomerCenterClose : SuperwallEvent()
    data class CustomerCenterAction(
        val action: com.superwall.sdk.customercenter.CustomerCenterAction,
        val pathId: String,
        val productId: String?
    ) : SuperwallEvent()
    data class CustomerCenterSurveyResponse(
        val surveyId: String,
        val optionId: String,
        val action: com.superwall.sdk.customercenter.CustomerCenterAction,
        val pathId: String,
        val productId: String?
    ) : SuperwallEvent()
    data class CustomerCenterRefundRequest(
        val productId: String,
        val status: CustomerCenterRefundStatus
    ) : SuperwallEvent()

    // System events
    data class DeviceAttributes(val attributes: Map<String, Any>) : SuperwallEvent()
    data class SurveyResponse(val survey: Survey, val selectedOption: SurveyOption, val customResponse: String?, val paywallInfo: PaywallInfo) : SuperwallEvent()
    class SurveyClose : SuperwallEvent()
    data class CustomPlacement(val name: String, val params: Map<String, Any>, val paywallInfo: PaywallInfo) : SuperwallEvent()
    object Reset : SuperwallEvent()

    // And more...
}

// Java - SuperwallEvent is a sealed class hierarchy
// Access via pattern matching or instanceof checks

Parameters

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

paywallInfo: PaywallInfo - Information about the paywall
data: PageViewData - Metadata for multi-page paywall navigation, including the page name, position in the flow, navigation type, and previous-page timing when available
product: StoreProduct - The product involved in transactions
url: String - Deep link URLs
attributes: Map<String, Any> - Device or user attributes
Customer Center events include screen, action, pathId, productId, surveyId, optionId, and refund status as applicable.

PaywallWebviewLoadTimeout is deprecated. This event was causing confusion due to its naming and has been removed from internal tracking. It will no longer fire.

New events in 2.7.10

PaywallPageView fires when a user navigates within a multi-page paywall. Use event.data.pageName, event.data.flowPosition, and event.data.navigationType to understand how they moved through the flow, and inspect the optional previous-page fields when you need timing context.

New events in 2.8.5

CustomerCenterOpen and CustomerCenterClose mark presentation and dismissal. CustomerCenterOpen.screen identifies the management or no-purchases screen.
CustomerCenterAction reports a selected path. CustomerCenterSurveyResponse reports its survey answer, and CustomerCenterRefundRequest reports the refund handoff result.
These events are delivered through SuperwallDelegate.handleSuperwallEvent(eventInfo) with the raw event names customerCenter_open, customerCenter_close, customerCenter_action, customerCenter_surveyResponse, and customerCenter_refundRequest.

New events in 2.6.6+

CustomerInfoDidChange fires whenever the SDK merges device, web, and external purchase controller data into a new CustomerInfo snapshot. The event includes the previous and next objects so you can diff entitlements or transactions.
PermissionRequested, PermissionGranted, and PermissionDenied correspond to the new Request permission action in the paywall editor. Each event carries the permissionName and paywallIdentifier.
PaywallPreloadStart and PaywallPreloadComplete track when preloading kicks off and how many paywalls finished warming the cache.

Example handler:

override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
    when (val event = eventInfo.event) {
        is SuperwallEvent.CustomerInfoDidChange -> {
            analytics.track("customer_info_updated", mapOf(
                "old_products" to event.from.activeSubscriptionProductIds.joinToString(),
                "new_products" to event.to.activeSubscriptionProductIds.joinToString()
            ))
        }
        is SuperwallEvent.PermissionRequested -> {
            analytics.track("permission_requested", mapOf(
                "permission" to event.permissionName,
                "paywall_id" to event.paywallIdentifier
            ))
        }
        is SuperwallEvent.PermissionGranted -> {
            featureFlags.unlock(event.permissionName)
        }
        is SuperwallEvent.PermissionDenied -> {
            showPermissionHelpSheet(event.permissionName)
        }
        is SuperwallEvent.PaywallPageView -> {
            analytics.track("paywall_page_view", mapOf(
                "paywall_id" to event.paywallInfo.id,
                "page_name" to event.data.pageName,
                "flow_position" to event.data.flowPosition,
                "navigation_type" to event.data.navigationType
            ))
        }
        is SuperwallEvent.PaywallPreloadComplete -> {
            Logger.i("Superwall", "Preloaded ${event.paywallCount} paywalls")
        }
        else -> Unit
    }
}

Purpose

Signature

Parameters

Returns / State

Usage

Deprecations in 2.7.0

New events in 2.7.10

New events in 2.8.5

New events in 2.6.6+

On this page