Request permissions from paywalls

Trigger the iOS system permission dialog directly from a Superwall paywall action.

Overview

Use the Request permission action in the paywall editor when you want to gate features behind iOS permissions without sending users into your app settings flow. When the user taps the element, SuperwallKit presents the native prompt, reports the result back to the paywall so you can update the design, and emits analytics events you can forward through SuperwallDelegate.

The Request permission action is rolling out to the paywall editor and is not visible in the dashboard just yet. We're shipping it very soon, so keep an eye on the changelog if you don't see it in your editor today.

Add the action in the editor

Open your paywall in the editor and select the button or element you want to wire up.
Set its action to Request permission.
Choose the permission to request. You can add multiple buttons if you need to prime more than one permission (for example, notification + camera).
Republish the paywall. No code changes are required beyond making sure the necessary Info.plist strings exist in your app.

Supported permissions and Info.plist keys

Editor option	`permission_type` sent from the paywall	Required Info.plist keys	Notes
Notifications	`notification`	None	Uses `UNUserNotificationCenter` with alert, badge, and sound options.
Location (When In Use)	`location`	`NSLocationWhenInUseUsageDescription`	Prompts for foreground access only.
Location (Always)	`background_location`	`NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription`	The SDK first ensures When-In-Use is granted, then escalates to Always.
Photos	`read_images`	`NSPhotoLibraryUsageDescription`	Requests `.readWrite` access on iOS 14+.
Contacts	`contacts`	`NSContactsUsageDescription`	Uses `CNContactStore.requestAccess`.
Camera	`camera`	`NSCameraUsageDescription`	Uses `AVCaptureDevice.requestAccess`.

If a required Info.plist key is missing—or the platform does not support the permission, such as background location on visionOS—the action finishes with an unsupported status, and the delegate receives a permissionDenied event so you can log the misconfiguration.

What the SDK tracks

Each button tap generates three analytics events that flow through handleSuperwallEvent(withInfo:):

permission_requested when the native dialog is about to appear.
permission_granted if the user allows access.
permission_denied if the user declines or the permission is unsupported on the current device.

All three events include:

{
  "permission_name": "<permission_type>",
  "paywall_identifier": "<id of the paywall that requested the permission>"
}

Use the associated SuperwallEvent.permissionRequested, .permissionGranted, and .permissionDenied cases to branch on outcomes:

func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
  switch eventInfo.event {
  case .permissionRequested(let permission, let paywallId):
    Analytics.track("permission_requested", with: [
      "permission": permission,
      "paywall_id": paywallId
    ])
  case .permissionGranted(let permission, _):
    FeatureFlags.unlock(permission: permission)
  case .permissionDenied(let permission, _):
    Alerts.presentPermissionDeclinedCopy(for: permission)
  default:
    break
  }
}

Status values returned to the paywall

The paywall receives a permission_result event with one of the following statuses so you can branch in your paywall logic (for example, swapping a button for a checklist item):

granted – The system reported success.
denied – The user denied the request or an earlier session already denied it.
unsupported – The permission is not available on the current device or the Info.plist copy block is missing.

Because the permissions are requested from real user interaction, you can safely stack actions—for example, ask for notifications first and, on success, show a camera prompt that immediately appears inside the same paywall session.

Troubleshooting

See unsupported? Double-check the Info.plist keys in the table above and confirm the permission exists on the target OS (background location is not available on visionOS).
Nothing happens when you tap the button? Make sure the action is published as Request permission and that the app has been updated with the new paywall revision.
Want to show fallback copy after a denial? Configure PaywallOptions.notificationPermissionsDenied or handle the permissionDenied event in your delegate to display a Settings deep link.