# PaywallOptions

Configuration for paywall presentation and behavior in the Superwall Android SDK.

> **Tip**

`PaywallOptions` is provided via the `paywalls` property on [`SuperwallOptions`](/docs/android/sdk-reference/SuperwallOptions) and is passed to the SDK when you call [`configure`](/docs/android/sdk-reference/configure).



Purpose [#purpose]

Customize how paywalls look and behave, including preload behavior, alerts, dismissal, and haptics.

Signature [#signature]

```kotlin
import com.superwall.sdk.analytics.Tier
import kotlin.time.Duration

class PaywallOptions {
    var isHapticFeedbackEnabled: Boolean = true

    class RestoreFailed {
        var title: String = "No Subscription Found"
        var message: String = "We couldn't find an active subscription for your account."
        var closeButtonTitle: String = "Okay"
    }
    var restoreFailed: RestoreFailed = RestoreFailed()

    var shouldShowPurchaseFailureAlert: Boolean = true
    var shouldPreload: Boolean = true
    var preloadDeviceOverrides: Map<Tier, Boolean> = emptyMap()
    var useCachedTemplates: Boolean = false
    var automaticallyDismiss: Boolean = true

    enum class TransactionBackgroundView { SPINNER }
    var transactionBackgroundView: TransactionBackgroundView? = TransactionBackgroundView.SPINNER

    var overrideProductsByName: Map<String, String> = emptyMap()
    var optimisticLoading: Boolean = false
    var timeoutAfter: Duration? = null
    var onBackPressed: ((PaywallInfo?) -> Boolean)? = null
}
```

Parameters [#parameters]

<TypeTable
  type="{
  isHapticFeedbackEnabled: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Enables haptic feedback when users purchase/restore, open links, or close the paywall.&#x22;,
    default: &#x22;true&#x22;,
  },
  restoreFailed: {
    type: &#x22;RestoreFailed&#x22;,
    description: &#x22;Messaging for the restore-failed alert.&#x22;,
    required: true,
  },
  &#x22;restoreFailed.title&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Title for restore-failed alert.&#x22;,
    default: &#x22;No Subscription Found&#x22;,
  },
  &#x22;restoreFailed.message&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Message for restore-failed alert.&#x22;,
    default: &#x22;We couldn't find an active subscription for your account.&#x22;,
  },
  &#x22;restoreFailed.closeButtonTitle&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Close button title for restore-failed alert.&#x22;,
    default: &#x22;Okay&#x22;,
  },
  shouldShowPurchaseFailureAlert: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Shows an alert after a purchase fails. Set to `false` if you handle failures via a `PurchaseController`.&#x22;,
    default: &#x22;true&#x22;,
  },
  shouldPreload: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Preloads and caches trigger paywalls and products during SDK initialization. Set to `false` for just-in-time loading.&#x22;,
    default: &#x22;true&#x22;,
  },
  preloadDeviceOverrides: {
    type: &#x22;Map<Tier, Boolean>&#x22;,
    description: &#x22;Overrides `shouldPreload` for specific device tiers. Any tier not listed here falls back to `shouldPreload`.&#x22;,
    default: &#x22;emptyMap()&#x22;,
  },
  useCachedTemplates: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Loads paywall template websites from disk when available.&#x22;,
    default: &#x22;false&#x22;,
  },
  automaticallyDismiss: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Automatically dismisses the paywall on successful purchase or restore.&#x22;,
    default: &#x22;true&#x22;,
  },
  transactionBackgroundView: {
    type: &#x22;TransactionBackgroundView?&#x22;,
    description: &#x22;View shown behind the system payment sheet during a transaction. Use `null` for no view.&#x22;,
    default: &#x22;.SPINNER&#x22;,
  },
  overrideProductsByName: {
    type: &#x22;Map<String, String>&#x22;,
    description: &#x22;Overrides products on all paywalls using name\u2192identifier mapping (e.g., `\&#x22;primary\&#x22;` \u2192 `\&#x22;com.example.premium_monthly\&#x22;`).&#x22;,
    required: true,
  },
  optimisticLoading: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Hides shimmer optimistically.&#x22;,
    default: &#x22;false&#x22;,
  },
  timeoutAfter: {
    type: &#x22;Duration?&#x22;,
    description: &#x22;Duration until a paywall timeout is invoked. When not using fallback loading, setting this triggers a timeout instead of retrying.&#x22;,
  },
  onBackPressed: {
    type: &#x22;((PaywallInfo?) -> Boolean)?&#x22;,
    description: &#x22;Callback invoked when back button is pressed (requires `reroute_back_button` enabled in paywall settings). Return `true` to consume the back press, `false` to use SDK default behavior.&#x22;,
    default: &#x22;null&#x22;,
  },
}"
/>

Usage [#usage]

```kotlin
val paywallOptions = PaywallOptions().apply {
    isHapticFeedbackEnabled = true
    shouldShowPurchaseFailureAlert = false
    shouldPreload = true
    preloadDeviceOverrides = mapOf(
        Tier.ULTRA_LOW to false,
        Tier.LOW to false,
    )
    useCachedTemplates = false
    automaticallyDismiss = true
    transactionBackgroundView = PaywallOptions.TransactionBackgroundView.SPINNER
    overrideProductsByName = mapOf(
        "primary" to "com.example.premium_monthly",
        "tertiary" to "com.example.premium_annual",
    )
    optimisticLoading = false
    timeoutAfter = null
    onBackPressed = { paywallInfo ->
        // Custom back button handling
        // Return true to consume the back press, false to use SDK default
        false
    }
}

val options = SuperwallOptions().apply {
    paywalls = paywallOptions
}

Superwall.configure(
    application = this,
    apiKey = "pk_your_api_key",
    options = options,
)
```

`preloadDeviceOverrides` is useful when you want to keep preloading enabled by default but disable it on lower-end devices. Tiers you do not specify continue to use the `shouldPreload` value.

Related [#related]

* [`SuperwallOptions`](/docs/android/sdk-reference/SuperwallOptions)