From 43349d75d7c14d9423b054b3efafd795c32d9fd2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 7 Jan 2026 18:49:19 +0000 Subject: [PATCH] feat: Add permission requests and preloading events Co-authored-by: duncan --- content/docs/ios/changelog.mdx | 12 +++ content/docs/ios/guides/advanced/meta.json | 1 + .../request-permissions-from-paywalls.mdx | 76 +++++++++++++++++++ content/docs/ios/index.mdx | 2 +- .../ios/sdk-reference/SuperwallDelegate.mdx | 10 +++ .../docs/ios/sdk-reference/SuperwallEvent.mdx | 47 +++++++++++- content/docs/ios/sdk-reference/index.mdx | 2 +- 7 files changed, 147 insertions(+), 3 deletions(-) create mode 100644 content/docs/ios/guides/advanced/request-permissions-from-paywalls.mdx diff --git a/content/docs/ios/changelog.mdx b/content/docs/ios/changelog.mdx index 8971182..0c320da 100644 --- a/content/docs/ios/changelog.mdx +++ b/content/docs/ios/changelog.mdx @@ -3,6 +3,18 @@ title: "Changelog" description: "Release notes for the Superwall iOS SDK" --- +## 4.12.0 + +### Enhancements + +- Adds `paywallPreload_start` and `paywallPreload_complete` events. +- Adds `request permission` action support allowing you to request notification, location, photos, contacts, and camera permissions from paywalls. +- Improves drawer presentation style corner rounding by applying the device radius on bottom corners. + +### Fixes + +- Updates Superscript version to 1.0.12. This fixes an issue with `appVersionPadded` comparison. View the original Rust release changelog [here](https://github.com/superwall/superscript/releases/tag/1.0.12). + ## 4.10.8 ### Enhancements diff --git a/content/docs/ios/guides/advanced/meta.json b/content/docs/ios/guides/advanced/meta.json index 46b0902..72c1bef 100644 --- a/content/docs/ios/guides/advanced/meta.json +++ b/content/docs/ios/guides/advanced/meta.json @@ -6,6 +6,7 @@ "using-the-presentation-handler", "viewing-purchased-products", "custom-paywall-actions", + "request-permissions-from-paywalls", "observer-mode", "direct-purchasing", "game-controller-support" diff --git a/content/docs/ios/guides/advanced/request-permissions-from-paywalls.mdx b/content/docs/ios/guides/advanced/request-permissions-from-paywalls.mdx new file mode 100644 index 0000000..dfa2644 --- /dev/null +++ b/content/docs/ios/guides/advanced/request-permissions-from-paywalls.mdx @@ -0,0 +1,76 @@ +--- +title: "Request permissions from paywalls" +description: "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`. + +## Add the action in the editor +1. Open your paywall in the editor and select the button or element you want to wire up. +2. Set its action to **Request permission**. +3. Choose the permission to request. You can add multiple buttons if you need to prime more than one permission (for example, notification + camera). +4. 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: + +```json +{ + "permission_name": "", + "paywall_identifier": "" +} +``` + +Use the associated `SuperwallEvent.permissionRequested`, `.permissionGranted`, and `.permissionDenied` cases to branch on outcomes: + +```swift +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. diff --git a/content/docs/ios/index.mdx b/content/docs/ios/index.mdx index 8146a2f..3d3ec2d 100644 --- a/content/docs/ios/index.mdx +++ b/content/docs/ios/index.mdx @@ -37,4 +37,4 @@ If you have feedback on any of our docs, please leave a rating and message at th If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-ios/issues). - \ No newline at end of file + \ No newline at end of file diff --git a/content/docs/ios/sdk-reference/SuperwallDelegate.mdx b/content/docs/ios/sdk-reference/SuperwallDelegate.mdx index c5d5e8c..310e55a 100644 --- a/content/docs/ios/sdk-reference/SuperwallDelegate.mdx +++ b/content/docs/ios/sdk-reference/SuperwallDelegate.mdx @@ -125,6 +125,16 @@ func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) { "product_id": product.id, "paywall_id": info.id ]) + case .permissionGranted(let permission, let paywallId): + Analytics.track("permission_granted", properties: [ + "permission": permission, + "paywall_id": paywallId + ]) + case .permissionDenied(let permission, let paywallId): + Analytics.track("permission_denied", properties: [ + "permission": permission, + "paywall_id": paywallId + ]) default: break } diff --git a/content/docs/ios/sdk-reference/SuperwallEvent.mdx b/content/docs/ios/sdk-reference/SuperwallEvent.mdx index e83734a..ffba120 100644 --- a/content/docs/ios/sdk-reference/SuperwallEvent.mdx +++ b/content/docs/ios/sdk-reference/SuperwallEvent.mdx @@ -35,6 +35,8 @@ public enum SuperwallEvent { case paywallClose(paywallInfo: PaywallInfo) case paywallDecline(paywallInfo: PaywallInfo) case paywallWebviewProcessTerminated(paywallInfo: PaywallInfo) + case paywallPreloadStart(paywallCount: Int) + case paywallPreloadComplete(paywallCount: Int) // Transaction events case transactionStart(product: StoreProduct, paywallInfo: PaywallInfo) @@ -52,6 +54,11 @@ public enum SuperwallEvent { // System events case deviceAttributes(attributes: [String: Any]) case reviewRequested(count: Int) + + // Permission events (Request permission action) + case permissionRequested(permissionName: String, paywallIdentifier: String) + case permissionGranted(permissionName: String, paywallIdentifier: String) + case permissionDenied(permissionName: String, paywallIdentifier: String) // And more... } @@ -64,9 +71,47 @@ Each event case contains associated values with relevant information for that ev - `url: URL` - Deep link URLs - `attributes: [String: Any]` - Device or user attributes - `count: Int` - For `reviewRequested`, the number of times a review has been requested (available in version 4.8.1+) +- `permissionName: String` / `paywallIdentifier: String` - The permission requested from the paywall and the identifier of the paywall that triggered it (new in 4.12.0). +- `paywallCount: Int` - Total number of paywalls being preloaded when `paywallPreloadStart`/`paywallPreloadComplete` fire (new in 4.12.0). ## Returns / State This is an enum that represents different event types. Events are received via [`SuperwallDelegate.handleSuperwallEvent(withInfo:)`](/ios/sdk-reference/SuperwallDelegate). ## Usage -These events are received via [`SuperwallDelegate.handleSuperwallEvent(withInfo:)`](/ios/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform. \ No newline at end of file +These events are received via [`SuperwallDelegate.handleSuperwallEvent(withInfo:)`](/ios/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform. + +## Permission events (4.12.0+) +When you wire the **Request permission** action in the paywall editor, the SDK emits `permission_requested`, `permission_granted`, and `permission_denied` events. Use them to track opt-in funnels or adapt your UI: + +```swift +func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) { + switch eventInfo.event { + case .permissionRequested(let permission, let paywallId): + logger.info("Prompting \(permission) from paywall \(paywallId)") + case .permissionGranted(let permission, _): + analytics.track("permission_granted", properties: eventInfo.params) + case .permissionDenied(let permission, _): + showSettingsNudge(for: permission) + default: + break + } +} +``` + +See the [Request permissions from paywalls guide](/ios/guides/advanced/request-permissions-from-paywalls) for setup details and Info.plist requirements. + +## Paywall preloading events (4.12.0+) +`paywallPreload_start` and `paywallPreload_complete` fire whenever the SDK preloads cached paywalls in the background. Both events include `paywall_count` inside `eventInfo.params`, and the enum cases expose the same value via `paywallCount`. This makes it easy to time or monitor cache warm-up: + +```swift +switch eventInfo.event { +case .paywallPreloadStart(let count): + Metrics.shared.begin("paywall_preload", metadata: ["count": count]) +case .paywallPreloadComplete(let count): + Metrics.shared.end("paywall_preload", metadata: ["count": count]) +default: + break +} +``` + +Pair these events with the [`shouldPreload`](/ios/sdk-reference/PaywallOptions#properties) option if you want to compare “on-demand” versus background caching strategies. \ No newline at end of file diff --git a/content/docs/ios/sdk-reference/index.mdx b/content/docs/ios/sdk-reference/index.mdx index 61f5e72..311ab80 100644 --- a/content/docs/ios/sdk-reference/index.mdx +++ b/content/docs/ios/sdk-reference/index.mdx @@ -15,4 +15,4 @@ If you have feedback on any of our docs, please leave a rating and message at th If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-ios/issues). - \ No newline at end of file + \ No newline at end of file