Request permissions from paywalls

Trigger Android runtime permission dialogs directly from a Superwall paywall action.

Overview

Use the Request permission action in the paywall editor when you want to gate features behind Android permissions without bouncing users back to native screens. When the user taps the element, the SDK:

Presents the corresponding Android system dialog.
Emits analytics events (permission_requested, permission_granted, permission_denied).
Sends the result back to the paywall so you can branch the UI (for example, swap a checklist item for a success state).

Add the action in the editor

Open your paywall, select the button (or any element) that should prompt the permission, and set its action to Request permission.
Choose the permission you want to request. You can wire multiple buttons if you need to prime several permissions in a single flow.
Republish the paywall. No extra SDK configuration is required beyond having the proper AndroidManifest.xml entries.

Declare the permissions in `AndroidManifest.xml`

Editor option	`permission_type` sent from the paywall	Required manifest entries	Notes
Notifications	`notification`	`<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />` (API 33+)	Devices below Android 13 do not require a runtime permission; the SDK reports `granted` immediately.
Location (Foreground)	`location`	`<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />`	Also covers coarse location because FINE implies COARSE.
Location (Background)	`background_location`	Foreground entry above and `<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />` (API 29+)	The SDK first ensures foreground access, then escalates to background.
Photos / Images	`read_images`	`<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />` (API 33+) or `READ_EXTERNAL_STORAGE` for older OS versions	Automatically picks the right permission at runtime.
Videos	`read_video`	`<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />` (API 33+) or `READ_EXTERNAL_STORAGE` pre-33
Contacts	`contacts`	`<uses-permission android:name="android.permission.READ_CONTACTS" />`
Camera	`camera`	`<uses-permission android:name="android.permission.CAMERA" />`

If a manifest entry is missing—or the permission is unsupported on the current OS level—the SDK responds with an unsupported status so you can show fallback copy.

Analytics and delegate callbacks

Forward the new events through SuperwallDelegate.handleSuperwallEvent to keep your analytics platform and feature flags in sync:

override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
  when (val event = eventInfo.event) {
    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 -> {
      Alerts.showPermissionDeclinedSheet(event.permissionName)
    }
    else -> Unit
  }
}

You can also log the newer customerInfoDidChange callback if the permission subsequently unlocks new paywalls that grant entitlements.

Status values returned to the paywall

The paywall receives a permission_result web event with:

granted – The system dialog reported success (or no dialog was needed).
denied – The user denied the request or previously denied it.
unsupported – The platform or manifest doesn't allow the requested permission.

Use Liquid or custom Javascript inside the paywall to branch on these statuses—for example, replace a “Grant notification access” button with a checkmark when the result equals granted.

Troubleshooting

Seeing unsupported? Double-check the manifest entries above and confirm the permission exists on the device's API level (for example, notification permissions only apply on Android 13+).
Nothing happens when you tap the button? Ensure the action is set to Request permission in the released paywall version.
Want to provide next steps after a denial? Listen for PermissionDenied in your delegate to deep-link users into Settings or show educational copy.