Superwall Android

https://github.com/superwall/superwall-android
Admin
Superwall Android is an open-source framework providing a WebView wrapper for presenting and...
Tokens:307,272
Snippets:2,143
Trust Score:9.3
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Basic Superwall.configure example

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Example from example/app/src/revenuecat/java/com/superwall/superapp/MainApplication.kt showing basic configuration with a purchase controller.

```kotlin
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Superwall.configure(
            this,
            Keys.EXAMPLE_KEY,
            purchaseController = RevenueCatPurchaseController(this),
        )
    }
}
```

--------------------------------

### getCustomerInfo usage example

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Example of retrieving customer info and iterating over subscriptions to print product IDs and active status.

```kotlin
val info = Superwall.instance.getCustomerInfo()
info.subscriptions.forEach { sub ->
    println("${sub.productId} active=${sub.isActive}")
}
```

--------------------------------

### PaywallBuilder usage example

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/presentation.md

Example of building a PaywallView using PaywallBuilder with params, overrides, delegate, shimmer view, purchase loading view, and activity. The build() call returns Result<PaywallView>.

```kotlin
val paywallView = PaywallBuilder("placement_name")
    .params(mapOf("key" to "value"))
    .overrides(PaywallOverrides())
    .delegate(myDelegate)
    .shimmerView(MyShimmerView(context))
    .purchaseLoadingView(MyPurchaseLoadingView(context))
    .activity(activity)
    .build()   // Result<PaywallView>
```

--------------------------------

### Install Maestro CLI on macOS

Source: https://github.com/superwall/superwall-android/blob/develop/test_app/README.md

Install Maestro CLI on macOS using Homebrew. Requires the mobile-dev-inc/tap tap and then installs the maestro package.

```bash
# macOS
 brew tap mobile-dev-inc/tap
 brew install maestro
```

--------------------------------

### RevenueCatPurchaseController implementation

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/delegate.md

Condensed example of a PurchaseController implementation using RevenueCat. It overrides purchase to fetch products and handle purchase errors, and restorePurchases to check for active entitlements. The example is from example/app/src/revenuecat/java/com/superwall/superapp/RevenueCatPurchaseController.kt.

```kotlin
class RevenueCatPurchaseController(val context: Context) : PurchaseController {
    override suspend fun purchase(
        activity: Activity,
        productDetails: ProductDetails,
        basePlanId: String?,
        offerId: String?,
    ): PurchaseResult {
        val products = Purchases.sharedInstance.awaitProducts(listOf(productDetails.productId))
        val product = products.firstOrNull() ?: return PurchaseResult.Failed("Product not found")
        return try {
            Purchases.sharedInstance.awaitPurchase(activity, product)
            PurchaseResult.Purchased()
        } catch (e: PurchasesException) {
            if (e.purchasesError.code == PurchasesErrorCode.PurchaseCancelledError) {
                PurchaseResult.Cancelled()
            } else {
                PurchaseResult.Failed(e.message ?: "Purchase failed due to an unknown error")
            }
        }
    }

    override suspend fun restorePurchases(): RestorationResult =
        try {
            if (hasAnyActiveEntitlements(Purchases.sharedInstance.awaitRestoration())) {
                RestorationResult.Restored()
            } else {
                RestorationResult.Failed(Exception("No active entitlements"))
            }
        } catch (e: Throwable) {
            RestorationResult.Failed(e)
        }
}
```

--------------------------------

### Superwall.configure with options and completion

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Example of Superwall.configure with a completion callback and options, including paywall preloading and event tracking behavior.

```kotlin
Superwall.configure(
    applicationContext = this,
    apiKey = "pk_...",
    options =
        SuperwallOptions().apply {
            paywalls =
                PaywallOptions().apply {
                    shouldPreload = true
                }
            eventTrackingBehavior = EventTrackingBehavior.ALL
        },
    completion = { result ->
        if (result.isSuccess) {
            // SDK ready
        } else {
            // result.exceptionOrNull() has the failure
        }
    },
)
```

--------------------------------

### Superwall.initialized

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Indicates whether the SDK has been successfully initialized. True only after configure's SDK setup completes successfully.

```APIDOC
## Superwall.initialized

### Description
Indicates whether the SDK has been successfully initialized. True only after configure's SDK setup completes successfully.

### Method
Property (companion object)

### Signature
```kotlin
var initialized: Boolean = false
```

### Behavior
- `true` only after `configure`'s SDK setup successfully completes.
- Used by delegate/callback code to guard calls (`Superwall.initialized` is checked in the example apps before touching the instance).
```

--------------------------------

### Example: setUserAttributes and identify

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/identity.md

Example usage from MainActivity.kt: sets a user attribute 'firstName' if the name is not blank, then calls identify with userId 'abc'. Demonstrates the typical sequence of setting attributes before identifying.

```kotlin
if (name.isNotBlank()) {
    Superwall.instance.setUserAttributes(
        mapOf(
            "firstName" to name,
        ),
    )
}
Superwall.instance.identify(userId = "abc")
```

--------------------------------

### Configure Superwall and access instance

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Shows the basic setup for Superwall in an Android app: configure the SDK in Application.onCreate with a public key and debug logging, then access the singleton and set a delegate elsewhere.

```kotlin
import com.superwall.sdk.Superwall

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Superwall.configure(
            this,
            "pk_live_...",
            options =
                SuperwallOptions().apply {
                    logging.level = LogLevel.debug
                },
        ) { result -> /* startup done */ }
    }
}

// Anywhere else in the app:
val paywallPresented = Superwall.instance.isPaywallPresented
Superwall.instance.delegate = object : SuperwallDelegate { /* ... */ }
```

--------------------------------

### Example usage of getPresentationResult

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/presentation.md

Shows how to call getPresentationResult and handle each possible result type. This does not present a paywall.

```kotlin
val result = Superwall.instance.getPresentationResult("campaign_trigger", mapOf("tier" to "gold"))
when (result.getOrThrow()) {
    is PresentationResult.Paywall -> { /* will show */ }
    is PresentationResult.Holdout -> { /* assigned to holdout */ }
    is PresentationResult.NoAudienceMatch -> { /* no rule matched */ }
    is PresentationResult.PlacementNotFound -> { /* not on dashboard */ }
    is PresentationResult.PaywallNotAvailable -> { /* no controller to present on */ }
}
```

--------------------------------

### Example: Fire a custom event with UserInitiatedEvent.Track

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/tracking.md

Shows how to call Superwall.instance.track with a UserInitiatedEvent.Track, including handling a failure result by printing the exception.

```kotlin
// Fire a custom event that may implicitly trigger a paywall
val result = Superwall.instance.track(
    UserInitiatedEvent.Track(
        rawName = "user_signed_up",
        canImplicitlyTriggerPaywall = false,
        isFeatureGatable = false,
        customParameters = mapOf("plan" to "pro"),
    ),
)
if (result.isFailure) {
    println("Tracking failed: ${result.exceptionOrNull()}")
}
```

--------------------------------

### Example usage of PaywallPresentationHandler

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/presentation.md

Shows how to create a PaywallPresentationHandler, register callbacks for dismiss, present, error, and skip events, and then register the handler with Superwall.instance.register for the placement 'campaign_trigger'.

```kotlin
val handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, paywallResult -> println("dismissed $paywallInfo - $paywallResult") }
handler.onPresent { paywallInfo -> println("presented $paywallInfo") }
handler.onError { error -> println("presentation failed with $error") }
handler.onSkip { reason ->
    when (reason) {
        is PaywallSkippedReason.PlacementNotFound -> {}
        is PaywallSkippedReason.Holdout -> {}
        is PaywallSkippedReason.NoAudienceMatch -> {}
        is PaywallSkippedReason.UserIsSubscribed -> {}
    }
}

Superwall.instance.register(placement = "campaign_trigger", handler = handler) {
    // feature code — remotely configurable to run always, or only when the user pays
}
```

--------------------------------

### GET /subscriptions-api/public/v1/products

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Test-mode product catalogue for the subscription host.

```APIDOC
## GET /subscriptions-api/public/v1/products

### Description
Test-mode product catalogue for the subscription host.

### Method
GET

### Endpoint
/subscriptions-api/public/v1/products

### Response
#### Success Response (200)
- **SuperwallProductsResponse** (Object) - The product catalogue response.
```

--------------------------------

### Superwall.configure

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Configures the Superwall SDK. Must be called exactly once on app launch. Initializes the SDK, restores subscription status, emits install event, and fetches configuration.

```APIDOC
## Superwall.configure

### Description
Configures the Superwall SDK. Must be called exactly once on app launch. Initializes the SDK, restores subscription status, emits install event, and fetches configuration.

### Method
Static function (companion object)

### Signature
```kotlin
@JvmStatic
@JvmOverloads
fun configure(
    applicationContext: Application,
    apiKey: String,
    purchaseController: PurchaseController? = null,
    options: SuperwallOptions? = null,
    activityProvider: ActivityProvider? = null,
    completion: ((Result<Unit>) -> Unit)? = null,
)
```

### Parameters
- **applicationContext** (Application) - Required - Your app's `Application` (Android)
- **apiKey** (String) - Required - Public API key from the Superwall dashboard
- **purchaseController** (PurchaseController?) - Optional - Implement to handle all subscription logic yourself; otherwise the SDK handles Google Play billing
- **options** (SuperwallOptions?) - Optional - See configuration.md
- **activityProvider** (ActivityProvider?) - Optional - Activity tracking hook (advanced)
- **completion** ((Result<Unit>) -> Unit?) - Optional - Called once SDK startup finishes or fails

### Behavior
- Call exactly once on app launch. Calling it again when `_instance != null` logs a warning and invokes `completion?.invoke(Result.success(Unit))` without reconfiguring.
- Initializes the `DependencyContainer`, configures storage under the API key, restores the cached subscription status, emits the install event, then concurrently fetches configuration and configures identity.
- On success: sets `initialized = true`, emits `hasInitialized` → `true`, invokes `completion` with `Result.success(Unit)` and logs `SDK Version - <version>` at `LogLevel.debug`.
- On failure: invokes `completion` with `Result.failure(Throwable)` and logs an error.

### Example
```kotlin
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Superwall.configure(
            this,
            Keys.EXAMPLE_KEY,
            purchaseController = RevenueCatPurchaseController(this),
        )
    }
}
```

With a completion callback and options:

```kotlin
Superwall.configure(
    applicationContext = this,
    apiKey = "pk_...",
    options =
        SuperwallOptions().apply {
            paywalls =
                PaywallOptions().apply {
                    shouldPreload = true
                }
            eventTrackingBehavior = EventTrackingBehavior.ALL
        },
    completion = { result ->
        if (result.isSuccess) {
            // SDK ready
        } else {
            // result.exceptionOrNull() has the failure
        }
    },
)
```
```

--------------------------------

### SuperwallEventInfo & placements

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/tracking.md

Documentation for the SuperwallEventInfo data class and the placements SharedFlow, including usage example.

```APIDOC
## `SuperwallEventInfo` & `placements`

### Description
`SuperwallEventInfo` is a data class that encapsulates a `SuperwallEvent` and its associated parameters. It is delivered to `SuperwallDelegate.handleSuperwallEvent(SuperwallEventInfo)` and emitted on `Superwall.instance.placements` (a `SharedFlow<SuperwallEventInfo>`) whenever a `TrackableSuperwallEvent` is tracked.

### Type
Data class

### Properties
- **event** (`SuperwallEvent`) - The event that occurred.
- **params** (`Map<String, Any>`) - Parameters associated with the event.

### Deprecated Members
- `SuperwallPlacementInfo` typealias - Deprecated, use `SuperwallEventInfo` instead.
- `placement` property - Deprecated, use `event` instead.

### Usage Example
```kotlin
Superwall.instance.placements.collect { info ->
    when (info.event) {
        is SuperwallEvent.PaywallOpen -> println("Paywall ${info.event.paywallInfo.identifier} opened")
        is SuperwallEvent.TriggerFire -> println("Trigger ${info.event.placementName}: ${info.event.result}")
        else -> {}
    }
}
```
```

--------------------------------

### Setting SuperwallDelegate with handleLog override

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/delegate.md

Example from example/app/src/main/java/com/superwall/superapp/MainActivity.kt showing how to set the delegate and override handleLog to capture error messages. The override checks for error level and productsManager scope before updating errorMessage.

```kotlin
Superwall.instance.delegate =
    object : SuperwallDelegate {
        override fun handleLog(
            level: String,
            scope: String,
            message: String?,
            info: Map<String, Any>?,
            error: Throwable?,
        ) {
            if (level == LogLevel.error.toString() &&
                scope == LogScope.productsManager.toString()
            ) {
                errorMessage.value = message
            }
            super.handleLog(level, scope, message, info, error)
        }
    }
```

--------------------------------

### GET /api/v1/static_config

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Fetches the full dashboard configuration including triggers, paywalls, products, and flags.

```APIDOC
## GET /api/v1/static_config

### Description
Fetches the full dashboard configuration including triggers, paywalls, products, and flags.

### Method
GET

### Endpoint
/api/v1/static_config

### Parameters
#### Query Parameters
- **pk** (string) - Required - The plain public API key.

### Response
#### Success Response (200)
- **Config** (object) - The decoded configuration object.

#### Error Response
- **NetworkError** - Non-2xx status codes, with types: NotAuthenticated, NotFound, Timeout, Decoding.

### Authentication
Bearer public key (query `pk` also sent).
```

--------------------------------

### Purchase with error handling using Superwall

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Use this Kotlin snippet to initiate a purchase with Superwall and handle the result. It covers success, pending, cancelled, and failed outcomes, as well as a failure result. The example calls `Superwall.instance.purchase` with a product identifier and uses a callback to process the `PurchaseResult`.

```kotlin
import com.superwall.sdk.Superwall
import com.superwall.sdk.delegate.PurchaseResult

Superwall.instance.purchase("com.example.premium_monthly") { result ->
    when (result) {
        is Result.Success -> {
            when (val outcome = result.value) {
                is PurchaseResult.Purchased -> unlockFeature()
                is PurchaseResult.Pending -> showPendingNotice()
                is PurchaseResult.Cancelled -> {}
                is PurchaseResult.Failed -> showError(outcome.errorMessage)
            }
        }
        is Result.Failure -> println("Purchase failed: ${result.error}")
    }
}
```

--------------------------------

### observe: Observer mode methods

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Observer mode methods for tracking purchase lifecycle events. Requires SuperwallOptions.shouldObservePurchases = true, otherwise logs an error. Tracks Transaction Start / Success / Fail analytics. Includes observe, observePurchaseStart, observePurchaseError, and observePurchaseResult.

```kotlin
fun observe(state: PurchasingObserverState)                                  // line 1301
fun observePurchaseStart(product: ProductDetails)                            // line 1350
fun observePurchaseError(product: ProductDetails, error: Throwable)          // line 1363
fun observePurchaseResult(billingResult: BillingResult, purchases: List<Purchase>)  // line 1379
```

--------------------------------

### GET /api/v1/paywalls

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Debugging endpoint that returns all paywalls. The `isForDebugging` flag switches the auth key.

```APIDOC
## GET /api/v1/paywalls

### Description
Debugging endpoint that returns all paywalls. The `isForDebugging` flag switches the auth key.

### Method
GET

### Endpoint
/api/v1/paywalls

### Response
#### Success Response (200)
- **paywalls** (List<Paywall>) - List of paywall objects.

### Authentication
Bearer public key (query `pk` also sent).
```

--------------------------------

### Superwall.initialized static property

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Static property that is true only after configure's SDK setup successfully completes. Used to guard calls before touching the instance.

```kotlin
var initialized: Boolean = false
```

--------------------------------

### CustomerInfo data class

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/entitlements.md

Data class modeling customer information. CustomerInfo.empty() returns a placeholder (isPlaceholder = true). Get it via Superwall.instance.getCustomerInfo() or observe Superwall.instance.customerInfo; CustomerInfoDidChange(from, to) fires when it changes.

```kotlin
@Serializable
data class CustomerInfo(
    @SerialName("subscriptions") val subscriptions: List<SubscriptionTransaction>,   // ascending purchase date
    @SerialName("nonSubscriptions") val nonSubscriptions: List<NonSubscriptionTransaction>,
    @SerialName("userId") val userId: String = "",
    @SerialName("entitlements") val entitlements: List<Entitlement>,
    @SerialName("isPlaceholder") internal val isPlaceholder: Boolean = false,
) {
    val activeSubscriptionProductIds: Set<String>
    fun toParams(): Map<String, Any?>   // empty map while isPlaceholder
    companion object {
        fun empty(): CustomerInfo
        fun forExternalPurchaseController(storage: Storage, subscriptionStatus: SubscriptionStatus): CustomerInfo
    }
}
```

--------------------------------

### GET /api/v1/paywall/<identifier>

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Fetches a single paywall by identifier. Cache-aware; query composition is load-bearing for cache eviction.

```APIDOC
## GET /api/v1/paywall/<identifier>

### Description
Fetches a single paywall by identifier. Cache-aware; query composition is load-bearing for cache eviction.

### Method
GET

### Endpoint
/api/v1/paywall/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The paywall identifier.

#### Query Parameters
- **pk** (string) - Required - The plain public API key.
- **locale** (string) - Optional - The device locale, included when the config's locale list contains the device locale or its language-only prefix.

### Response
#### Success Response (200)
- **Paywall** (object) - The requested paywall.

### Note
Called with `isForDebugging = true`.
```

--------------------------------

### StoreProductType Interface

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

The StoreProductType interface exposes the pricing and trial surface of every product. It contains read-only properties for identifiers, prices, subscription periods, trial details, and locale information, plus a method to get the trial price per unit.

```APIDOC
## StoreProductType Interface

### Description
The `StoreProductType` interface represents the pricing and trial surface of every product. It is delegated to by `StoreProduct` and provides read-only access to product identifiers, prices, subscription periods, trial details, and locale information.

### Properties

- **fullIdentifier** (`String`) - e.g. `com.example.premium:monthly:sw-auto`
- **productIdentifier** (`String`) - Base product id
- **price** (`BigDecimal`) - Price of the selected offer (USD)
- **localizedPrice** (`String`) - Formatted with device locale/currency
- **localizedSubscriptionPeriod** / **period** / **periodly** (`String`) - Period descriptions
- **periodDays/Weeks/Months/Years** (+ `String` variants) (`Int`) - Period decompositions
- **dailyPrice** / **weeklyPrice** / **monthlyPrice** / **yearlyPrice** (`String`) - Per-unit prices (`"n/a"` for one-time)
- **hasFreeTrial** (`Boolean`) - Trial present on selected offer
- **trialPeriodPrice** (`BigDecimal`) - Intro/discounted trial price
- **localizedTrialPeriodPrice** (`String`) - Formatted intro price
- **trialPeriodEndDate** / **trialPeriodEndDateString** (`Date?` / `String`) - End of trial
- **trialPeriodDays/Weeks/Months/Years** (+ `String`) (`Int`) - Trial decomposition (30d month / 7d week / 365d year: `"${units * 30}-day"` etc. for `trialPeriodText`)
- **trialPeriodText** (`String`) - e.g. `"7-day"`
- **locale**, **languageCode**, **currencyCode**, **currencySymbol**, **regionCode** (`String?`) - Device/product locale info
- **subscriptionPeriod** (`SubscriptionPeriod?`) - Billing period
- **productType** (`String`) - Underlying Google Play product type
- **storeFrontCountryCode** (`String?`) - `null` for Play Store, set for API products
- **attributes** (`Map<String, String>`) - Flattened map of all of the above (used in templates/analytics)

### Methods

- **trialPeriodPricePerUnit(unit: SubscriptionPeriod.Unit)** (`String`) - Intro price normalized to a unit
```

--------------------------------

### Fetch and purchase a product with Superwall

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

Fetches products by identifier, retrieves one, prints its price and trial info, then purchases it. Uses `getOrThrow()` and requires a non-null product before proceeding.

```kotlin
val products = Superwall.instance.getProducts("com.example.premium_monthly", "com.example.premium_annual")
val product = products.getOrThrow()["com.example.premium_monthly"] ?: return

println("${product.productIdentifier} — ${product.localizedPrice}/${product.period}")
if (product.hasFreeTrial) {
    println("Free trial: ${product.trialPeriodText}, ends ${product.trialPeriodEndDateString}")
}
// Purchase it:
val result = Superwall.instance.purchase(product)
```

--------------------------------

### GET /api/v1/assignments

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Fetches stored experiment assignments for the user.

```APIDOC
## GET /api/v1/assignments

### Description
Fetches stored experiment assignments for the user.

### Method
GET

### Endpoint
/api/v1/assignments

### Response
#### Success Response (200)
- **assignments** (MutableList<Assignment>) - List of assignments.
- **Assignment** (object) - Contains `experimentId` (string) and `variantId` (string).
```

--------------------------------

### GET /subscriptions-api/public/v1/users/<id>/entitlements

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/endpoints.md

Poll web entitlements for a user or device.

```APIDOC
## GET /subscriptions-api/public/v1/users/<id>/entitlements

### Description
Poll web entitlements for a user or device.

### Method
GET

### Endpoint
/subscriptions-api/public/v1/users/<id>/entitlements

### Parameters
#### Path Parameters
- **id** (String) - Required - The app user id (`users/<userId>/entitlements`) or, for `webEntitlementsByDeviceID`, the device vendor id (`users/<deviceId>/entitlements`).

#### Query Parameters
- **deviceId** (String) - Required - The device vendor id.

### Response
#### Success Response (200)
- **customerInfo** (CustomerInfo?) - Optional - Customer information.

### Error Handling
- **Timeout** - 5s.
```

--------------------------------

### Superwall.instance.options

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

The options passed to `configure`. This property is read-only and defaults to `null`→defaults.

```APIDOC
## Superwall.instance.options

### Description
The options passed to `configure`. This property is read-only and defaults to `null`→defaults.

### Property
- **Type**: `SuperwallOptions`
- **Read-only**: yes
- **Default**: `null`→defaults

### Usage
```kotlin
val options = Superwall.instance.options
```
```

--------------------------------

### Build test app for Maestro with SDK version

Source: https://github.com/superwall/superwall-android/blob/develop/test_app/README.md

Build the test app for Maestro with a specific SDK version and environment. Supported environments are dev, release, and custom (add -Pendpoint=<endpointHere> for custom).

```bash
./gradlew :test_app:buildForMaestro -Psdk-version=2.5.0 -Penv=dev
```

--------------------------------

### Build and Test Commands

Source: https://github.com/superwall/superwall-android/blob/develop/CLAUDE.md

Common Gradle commands for building, testing, and publishing the Superwall Android SDK. Includes unit tests, instrumentation tests, screenshot recording, local publishing, and build info generation.

```bash
# Build the project
./gradlew build

# Run unit tests
./gradlew test

# Run instrumentation tests (requires connected device/emulator)
./gradlew :app:connectedCheck

# Run integration tests with screenshot recording
./gradlew recordDebugAndroidTestScreenshots

# Build and publish SDK locally
./gradlew publishToMavenLocal

# Generate build info
./gradlew generateBuildInfo
```

--------------------------------

### Superwall.instance.configurationState

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Current configuration state: `Pending` / `Configured` / `Failed`.

```APIDOC
## Superwall.instance.configurationState

### Description
Current configuration state: `Pending` / `Configured` / `Failed`.

### Property
- **Type**: `ConfigurationStatus`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
val state = Superwall.instance.configurationState
```
```

--------------------------------

### SuperwallOptions.Logging

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/configuration.md

Configuration for console logging. Allows setting the minimum log level and the scopes to print.

```kotlin
class Logging() {
    constructor(definition: Logging.() -> Unit) : this() { definition() }
    var level: LogLevel = LogLevel.warn          // min level printed to console
    var scopes: EnumSet<LogScope> = EnumSet.of(LogScope.all)   // scopes to print
}
```

--------------------------------

### Error Reference

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/errors.md

Reference for custom error types (NetworkError, BillingError, TransactionError) surfaced by the Superwall Android SDK, including trigger conditions and catch examples.

```APIDOC
## [SDK] Error Handling Reference

### Description
This reference documents the custom error types that the Superwall Android SDK surfaces through `Result` values, delegate callbacks, or thrown `Throwable`s. It explains the trigger conditions for each error and how to catch them.

### Error Types

#### `sealed class NetworkError`

- **Unknown** - Non-HTTP failure (connectivity, DNS, TLS, malformed response).
- **NotAuthenticated** - HTTP 401/403 - invalid or revoked API key.
- **Timeout** - Request exceeded its timeout budget.
- **Decoding** - Response body failed to decode into the expected model.
- **NotFound** - HTTP 404 (e.g., paywall not found, config missing).
- **InvalidUrl** - Malformed URL passed to the network layer.

#### `sealed class BillingError`

- **UnknownError** - Internal billing client failure with no code.
- **IllegalStateException** - Billing client connection state invalid.
- **BillingNotAvailable(description)** - Billing is unavailable; description from the billing client.
- **WithCode(code, description)** - Google Play Billing error code / description.

#### `sealed class TransactionError`

- **Pending** - Purchase returned a pending state (payment requires developer action).
- **Failure** - Purchase failed; carries the attempted `product`.

### Usage

Errors are returned inside `Result.failure(...)` values, in delegate callbacks (`PaywallPresentationHandler.onError`), or as thrown `Throwable`s where noted. The SDK never throws for expected failures; most operations return `kotlin.Result<T>` / `Either<T, E>`.

### Example: Catching NetworkError

```kotlin
val result = Superwall.instance.getProducts("com.x")  // Result-wrapped
if (result.isFailure) {
    when (val e = result.exceptionOrNull()) {
        is NetworkError.NotAuthenticated -> reConfig()
        is NetworkError.Timeout -> retryLater()
        is NetworkError.NotFound -> // product catalogue not found
        is NetworkError.Decoding -> // schema mismatch
        else -> {}
    }
}
```

### Example: Catching BillingError

```kotlin
val result = Superwall.instance.consume(token)
when (result) {
    is Result.Success -> markConsumed(result.value)
    is Result.Failure -> when (result.error) {
        is BillingError -> println("Billing error ${result.error.code}: ${result.error.description}")
        else -> println("Store communication failure")
    }
}
```
```

--------------------------------

### RawStoreProduct class wrapping ProductDetails

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

Wraps Google Play ProductDetails. The companion object's from(details) constructs a RawStoreProduct. SelectedOfferDetails is sealed: Subscription(underlying: SubscriptionOfferDetails) or OneTime(underlying: OneTimePurchaseOfferDetails, purchaseOptionId: String?, offerId: String?).

```kotlin
class RawStoreProduct(
    val underlyingProductDetails: ProductDetails,
    override val fullIdentifier: String,
    val basePlanType: BasePlanType,
    private val offerType: OfferType,
) : StoreProductType {
    val basePlanId: String?
    val selectedOffer: SelectedOfferDetails?
    internal val offerId: String?
    companion object { fun from(details: ProductDetails): RawStoreProduct }
}
```

--------------------------------

### Superwall.instance.purchase

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

Purchases a given product using the Superwall SDK.

```APIDOC
## [SDK] Superwall.instance.purchase

### Description
Purchases a given product using the Superwall SDK.

### Method
SDK method call

### Endpoint
Superwall.instance.purchase(product: StoreProduct)

### Parameters
- **product** (StoreProduct) - Required - The product to purchase.

### Request Example
```kotlin
val result = Superwall.instance.purchase(product)
```

### Response
#### Success Response
- **result** (PurchaseResult) - The result of the purchase attempt.
```

--------------------------------

### Superwall.instance.configurationStateListener

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Emits each configuration state change.

```APIDOC
## Superwall.instance.configurationStateListener

### Description
Emits each configuration state change.

### Property
- **Type**: `Flow<ConfigurationStatus>`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
Superwall.instance.configurationStateListener.collect { state ->
  // handle state change
}
```
```

--------------------------------

### Observe and set subscription status with Superwall.instance

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/entitlements.md

Shows how to set and observe subscription status using Superwall.instance.setSubscriptionStatus() and the subscriptionStatus flow. The shortcut with a vararg of entitlement IDs maps to Active, while the no-arg call maps to Inactive.

```kotlin
import com.superwall.sdk.models.entitlements.SubscriptionStatus
import com.superwall.sdk.models.entitlements.Entitlement

// Grant access (e.g. after your own purchase flow):
Superwall.instance.setSubscriptionStatus(
    SubscriptionStatus.Active(setOf(Entitlement("premium")))
)

// Observe changes:
Superwall.instance.subscriptionStatus.collect { status ->
    when (status) {
        is SubscriptionStatus.Active -> println("Active: ${status.entitlements.map { it.id }}")
        is SubscriptionStatus.Inactive -> println("Inactive")
        is SubscriptionStatus.Unknown -> println("Unknown")
    }
}

// Shortcut with entitlements array:
Superwall.instance.setSubscriptionStatus("default", "pro")   // == Active({default, pro})
Superwall.instance.setSubscriptionStatus()                    // == Inactive
```

--------------------------------

### Superwall.instance.getProducts

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

Fetches products by their identifiers from the Superwall SDK.

```APIDOC
## [SDK] Superwall.instance.getProducts

### Description
Fetches the products with the given identifiers from the Superwall SDK.

### Method
SDK method call

### Endpoint
Superwall.instance.getProducts(productIdentifiers: String...)

### Parameters
- **productIdentifiers** (String...) - Required - The product identifiers to fetch.

### Request Example
```kotlin
val products = Superwall.instance.getProducts("com.example.premium_monthly", "com.example.premium_annual")
```

### Response
#### Success Response
- **products** (Map<String, StoreProduct>) - A map of product identifiers to StoreProduct objects.

#### Response Example
```kotlin
val product = products.getOrThrow()["com.example.premium_monthly"] ?: return
```
```

--------------------------------

### Superwall Class Reference

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Documentation for the Superwall singleton class, including configuration and instance access.

```APIDOC
## [SDK] Superwall.configure

### Description
Configures the Superwall SDK once at app launch with the provided API key and options.

### Method
configure

### Parameters
- **context** (Context) - Required - The application context.
- **apiKey** (String) - Required - The API key for Superwall.
- **purchaseController** (PurchaseController?) - Optional - A purchase controller for handling purchases.
- **options** (SuperwallOptions?) - Optional - Configuration options for the SDK.
- **activityProvider** (ActivityProvider?) - Optional - Provides the current activity.
- **completion** ((Result<Unit>) -> Unit)?) - Optional - Completion callback with the result of configuration.

### Response
- **Result<Unit>** - The result of the configuration operation.

## [SDK] Superwall.instance

### Description
Provides access to the singleton instance of the Superwall SDK after configuration.

### Method
instance

### Response
- **Superwall** - The singleton instance of the Superwall SDK.

## [SDK] Superwall.eventDidOccur

### Description
Callback method for paywall view events, part of the PaywallViewEventCallback interface.

### Method
eventDidOccur

### Parameters
- **event** (PaywallViewEvent) - Required - The event that occurred.

### Response
- **Unit** - No return value.
```

--------------------------------

### Superwall.openRestoreOnWeb

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/web-redemption.md

Opens config.webToAppConfig.restoreAccesUrl in the default browser. Logs an error and returns if the configuration is not available.

```kotlin
fun Superwall.openRestoreOnWeb()
```

--------------------------------

### getCustomerInfo method

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Returns a synchronous snapshot of the latest merged CustomerInfo. The observable version is available via Superwall.instance.customerInfo.

```kotlin
fun getCustomerInfo(): CustomerInfo = _customerInfo.value
```

--------------------------------

### Superwall.setUserAttributes function signature

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/identity.md

Signature for the Superwall.setUserAttributes extension function. It takes a map of custom user properties (JSON-encodable values, URLs, or Dates), returns Unit, merges attributes by key (overwriting existing keys without removing others), and tracks a user_attributes event. Keys starting with $ are reserved and dropped; arrays/dicts as values are unsupported and dropped.

```kotlin
fun Superwall.setUserAttributes(attributes: Map<String, Any?>)
```

--------------------------------

### Superwall.instance.localResources

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Local `swlocal://` assets. This property is settable and defaults to `emptyMap()`.

```APIDOC
## Superwall.instance.localResources

### Description
Local `swlocal://` assets. This property is settable and defaults to `emptyMap()`.

### Property
- **Type**: `Map<String, PaywallResource>`
- **Read-only**: no
- **Default**: `emptyMap()`

### Usage
```kotlin
Superwall.instance.localResources = mapOf("resource" to resource)
```
```

--------------------------------

### getProducts: Retrieve products by identifiers

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Returns a Result containing a map of product identifier to StoreProduct for the given product IDs.

```kotlin
suspend fun getProducts(vararg productIds: String): Result<Map<String, StoreProduct>>
```

--------------------------------

### Superwall.instance

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Returns the singleton Superwall instance. Throws IllegalStateException if the SDK has not been initialized or configured.

```APIDOC
## Superwall.instance

### Description
Returns the singleton Superwall instance. Throws IllegalStateException if the SDK has not been initialized or configured.

### Method
Property getter (companion object)

### Signature
```kotlin
val instance: Superwall
    get() =
        _instance
            ?: throw IllegalStateException("Superwall has not been initialized or configured.")
```

### Throws
- **IllegalStateException** - If `configure` was never called.
```

--------------------------------

### Run all Maestro tests

Source: https://github.com/superwall/superwall-android/blob/develop/test_app/README.md

Run all Maestro tests in the test_app/maestro/ directory.

```bash
maestro test test_app/maestro/
```

--------------------------------

### SuperwallOptions.NetworkEnvironment

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/configuration.md

Defines the network environment options for Superwall. Includes predefined environments (Release, ReleaseCandidate, Developer) and a Custom class for overriding host details.

```kotlin
open class NetworkEnvironment(open val hostDomain: String) {
    open val baseHost: String          get() = "api.$hostDomain"
    open val collectorHost: String     get() = "collector.$hostDomain"
    open val subscriptionHost: String  get() = if (this is Release) "subscriptions-api.superwall.com" else "subscriptions-api.superwall.dev"
    open val scheme: String            get() = "https"
    open val enrichmentHost: String    get() = if (this is Release) "enrichment-api.superwall.com" else "enrichment-api.superwall.dev"
    open val port: Int?                get() = null

    class Release : NetworkEnvironment("superwall.me")
    class ReleaseCandidate : NetworkEnvironment("superwallcanary.com")
    class Developer : NetworkEnvironment("superwall.dev")
    class Custom(override val baseHost: String, override val collectorHost: String,
                 override val scheme: String, override val port: Int?) : NetworkEnvironment(baseHost)
}
```

--------------------------------

### observe (observer mode)

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Observer mode methods to track purchase lifecycle events. Requires `SuperwallOptions.shouldObservePurchases = true`.

```APIDOC
## observe (observer mode)

### Description
Observer mode methods to track purchase lifecycle events. Requires `SuperwallOptions.shouldObservePurchases = true`, otherwise logs an error. Tracks Transaction Start / Success / Fail analytics.

### Methods
```kotlin
fun observe(state: PurchasingObserverState)
fun observePurchaseStart(product: ProductDetails)
fun observePurchaseError(product: ProductDetails, error: Throwable)
fun observePurchaseResult(billingResult: BillingResult, purchases: List<Purchase>)
```

### Parameters
- `state` (PurchasingObserverState) - Required - The observer state, sealed with three cases: `PurchaseWillBegin`, `PurchaseResult`, `PurchaseError`.
- `product` (ProductDetails) - Required - The product involved in the purchase.
- `error` (Throwable) - Required - The error that occurred.
- `billingResult` (BillingResult) - Required - The billing result.
- `purchases` (List<Purchase>) - Required - The list of purchases.

### Return
`Unit`

```

--------------------------------

### Superwall.instance.paywallView

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

The currently presented paywall view, if any.

```APIDOC
## Superwall.instance.paywallView

### Description
The currently presented paywall view, if any.

### Property
- **Type**: `PaywallView?`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
val view = Superwall.instance.paywallView
```
```

--------------------------------

### BasePlanType and OfferType sealed classes

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/store.md

Both sealed classes are defined in StoreProduct.kt. BasePlanType.from maps ""/null/"sw-auto" to Auto. OfferType.from maps "sw-auto"/""/null to Auto and "sw-none" to None; toOffer() returns Offer.Automatic(), Offer.NoOffer, or Offer.Specified(offerIdentifier). Offer auto-selection for subscriptions filters out -ignore-offer-tagged offers, prefers the longest free trial, then the cheapest non-free offer.

```kotlin
@Serializable
sealed class BasePlanType {
    object Auto : BasePlanType()
    data class Specific(val id: String) : BasePlanType()
    val specificId: String?
    companion object { fun from(value: String?): BasePlanType }  // ""/null/"sw-auto" => Auto
}
```

```kotlin
@Serializable
sealed class OfferType {
    object Auto : OfferType()
    object None : OfferType()
    data class Specific(val id: String) : OfferType()
    val specificId: String?
    fun toOffer(): Offer   // Offer.Automatic() | Offer.NoOffer | Offer.Specified(offerIdentifier)
    companion object { fun from(value: String?): OfferType }  // "sw-auto"/""/null => Auto, "sw-none" => None
}
```

--------------------------------

### Superwall.configure full signature

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Full signature of the static Superwall.configure method. Call exactly once on app launch; calling again logs a warning and invokes the completion callback with success without reconfiguring.

```kotlin
@JvmStatic
@JvmOverloads
fun configure(
    applicationContext: Application,
    apiKey: String,
    purchaseController: PurchaseController? = null,
    options: SuperwallOptions? = null,
    activityProvider: ActivityProvider? = null,
    completion: ((Result<Unit>) -> Unit)? = null,
)
```

--------------------------------

### Superwall.openRestoreOnWeb

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/web-redemption.md

Opens the configured restore access URL in the default browser. Logs an error and returns if the configuration is not available.

```APIDOC
## [METHOD] Superwall.openRestoreOnWeb

### Description
Opens `config.webToAppConfig.restoreAccesUrl` in the default browser. Logs an error and returns if the configuration is not available.

### Method
FUNCTION

### Endpoint
`Superwall.openRestoreOnWeb()`

### Parameters
None

### Request Example
```kotlin
Superwall.openRestoreOnWeb()
```

### Response
#### Success Response
No return value.

#### Error Handling
Logs an error if the configuration is not available.
```

--------------------------------

### SuperwallOptions constructor

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/configuration.md

Constructor for SuperwallOptions that accepts a lambda for configuration. Used when passing options to Superwall.configure().

```kotlin
class SuperwallOptions() {
    constructor(definition: SuperwallOptions.() -> Unit) : this() { definition() }
    ...
}
```

--------------------------------

### Superwall.handleDeepLink static method

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Static method to handle a deep link (paywall preview or redemption code). Safe to call before configure; unconfigured links are queued and processed once configured. Returns success if the link was a Superwall link, failure otherwise.

```kotlin
fun handleDeepLink(uri: Uri): Result<Boolean> = DeepLinkRouter.handleDeepLink(uri)
```

--------------------------------

### PaywallOptions class definition

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/configuration.md

Defines the PaywallOptions class with a primary constructor and a secondary constructor that accepts a lambda for configuration. The ellipsis indicates additional properties and methods not shown.

```kotlin
class PaywallOptions() {
    constructor(definition: PaywallOptions.() -> Unit) : this() { definition() }
    ...
}
```

--------------------------------

### Superwall.instance.entitlements

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Entitlement facade.

```APIDOC
## Superwall.instance.entitlements

### Description
Entitlement facade.

### Property
- **Type**: `Entitlements`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
val entitlements = Superwall.instance.entitlements
```
```

--------------------------------

### Superwall.instance.customerInfo

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Latest merged customer info flow.

```APIDOC
## Superwall.instance.customerInfo

### Description
Latest merged customer info flow.

### Property
- **Type**: `StateFlow<CustomerInfo>`
- **Read-only**: yes
- **Default**: `CustomerInfo.empty()`

### Usage
```kotlin
Superwall.instance.customerInfo.collect { info ->
  // handle customer info
}
```
```

--------------------------------

### Superwall.register: Register a paywall presentation

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/presentation.md

Registers a paywall presentation for a placement. The placement must match a campaign rule configured on the Superwall dashboard. Params with `$`-prefixed keys are dropped; URL and Date values are supported. The feature block is called on dismiss or if the user already pays for non-gated paywalls, only when paying or beginning to pay for gated paywalls, and immediately when no paywall is configured; it is never called on error (use the handler).

```kotlin
@JvmOverloads
fun Superwall.register(
    placement: String,
    params: Map<String, Any>? = null,
    handler: PaywallPresentationHandler? = null,
    feature: (() -> Unit)? = null,
)
```

--------------------------------

### Superwall.instance.latestPaywallInfo

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

Info of the most recently presented view.

```APIDOC
## Superwall.instance.latestPaywallInfo

### Description
Info of the most recently presented view.

### Property
- **Type**: `PaywallInfo?`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
val info = Superwall.instance.latestPaywallInfo
```
```

--------------------------------

### getCustomerInfo

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall-methods.md

Returns a synchronous snapshot of the latest merged CustomerInfo, including subscriptions, non-subscription transactions, and entitlements.

```APIDOC
## getCustomerInfo

### Description
Returns a synchronous snapshot of the latest merged CustomerInfo, including subscriptions, non-subscription transactions, and entitlements.

### Method
`fun getCustomerInfo(): CustomerInfo`

### Return
`CustomerInfo` - The latest merged customer information.

### Example
```kotlin
val info = Superwall.instance.getCustomerInfo()
info.subscriptions.forEach { sub ->
    println("${sub.productId} active=${sub.isActive}")
}
```
```

--------------------------------

### Superwall.instance.integrationAttributes

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/superwall.md

3rd-party integration identifiers.

```APIDOC
## Superwall.instance.integrationAttributes

### Description
3rd-party integration identifiers.

### Property
- **Type**: `Map<String, String>`
- **Read-only**: yes
- **Default**: —

### Usage
```kotlin
val attrs = Superwall.instance.integrationAttributes
```
```

--------------------------------

### Forward game-controller events to paywall

Source: https://github.com/superwall/superwall-android/blob/develop/_autodocs/api-reference/misc-utilities.md

Forwards game-controller events into the paywall via `window.paywall.accept([...])`. Requires `SuperwallOptions.isGameControllerEnabled = true`.

```kotlin
public fun Superwall.dispatchKeyEvent(keyEvent: KeyEvent)      // line 23
public fun Superwall.dispatchMotionEvent(motionEvent: MotionEvent)  // line 37
```

--------------------------------

### Run a single Maestro test

Source: https://github.com/superwall/superwall-android/blob/develop/test_app/README.md

Run a single Maestro test flow from the specified YAML file.

```bash
maestro test test_app/maestro/flow.yaml
```
Tokens:
Raw