feat: Update for iOS SDK 4.12.0

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

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"

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": "<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:
+
+```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.

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).
 
-<SdkLatestVersion version="4.11.2" repoUrl="https://github.com/superwall/Superwall-iOS" />
+<SdkLatestVersion version="4.12.0" repoUrl="https://github.com/superwall/Superwall-iOS" />

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
   }

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.
+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.

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).
 
-<SdkLatestVersion version="4.11.2" repoUrl="https://github.com/superwall/Superwall-iOS" />
+<SdkLatestVersion version="4.12.0" repoUrl="https://github.com/superwall/Superwall-iOS" />