# SuperwallEvent

A sealed class representing analytical events that are automatically tracked by Superwall.

> **Info**

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.



> **Tip**

Common events to track for conversion analysis include `TriggerFire`, `PaywallOpen`, `TransactionStart`, and `TransactionComplete`.



Purpose [#purpose]

Represents internal analytics events tracked by Superwall and sent to the [`SuperwallDelegate`](/docs/android/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform.

Signature [#signature]

```kotlin
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()

    // 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
// Java - SuperwallEvent is a sealed class hierarchy
// Access via pattern matching or instanceof checks
```

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

Returns / State [#returns--state]

This is a sealed class that represents different event types. Events are received via [`SuperwallDelegate.handleSuperwallEvent(eventInfo)`](/docs/android/sdk-reference/SuperwallDelegate).

Usage [#usage]

These events are received via [`SuperwallDelegate.handleSuperwallEvent(eventInfo)`](/docs/android/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform.

Deprecations in 2.7.0 [#deprecations-in-270]

* `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 [#new-events-in-2710]

* `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.6.6+ [#new-events-in-266]

* `CustomerInfoDidChange` fires whenever the SDK merges device, web, and external purchase controller data into a new [`CustomerInfo`](/docs/android/quickstart/tracking-subscription-state#reading-detailed-purchase-history-2-6-6) 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:

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