4.15.1

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 The changelog for `SuperwallKit`. Also see the [releases](https://github.com/superwall/Superwall-iOS/releases) on GitHub.
 
+## 4.15.1
+
+### Enhancements
+
+- Adds an `onCustomCallback` parameter to `getPaywall`.
+- `SuperwallOptions.localResources` now accepts UIImage's from xcasset files, e.g. `UIImage(named: "my-image")`.
+- Exposes abandoned transaction product params in audience filters.
+
+### Fixes
+
+- Sanitizes email user attribute.
+
 ## 4.15.0
 
 ### Enhancements

Sources/SuperwallKit/Analytics/Internal Tracking/Trackable Events/TrackableSuperwallEvent.swift

@@ -671,6 +671,9 @@ enum InternalSuperwallEvent {
         var params = paywallInfo.audienceFilterParams()
         if let product = product {
           params["abandoned_product_id"] = product.productIdentifier
+          for (key, value) in product.attributes where key != "identifier" {
+            params["abandoned_product_\(key.camelCaseToSnakeCase())"] = value
+          }
         }
         return params
       default:

Sources/SuperwallKit/Config/ConfigLogic.swift

@@ -306,8 +306,7 @@ enum ConfigLogic {
     from config: Config
   ) -> [String: Set<Entitlement>] {
     return Dictionary(
-      config.products.map { ($0.id, $0.entitlements) },
-      uniquingKeysWith: { $0.union($1) }
-    )
+      config.products.map { ($0.id, $0.entitlements) }
+    ) { $0.union($1) }
   }
 }

Sources/SuperwallKit/Config/Options/AssetResource.swift

@@ -0,0 +1,33 @@
+//
+//  AssetResource.swift
+//  SuperwallKit
+//
+//  Created by Yusuf Tör on 24/04/2026.
+//
+
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// A type that can be registered against ``SuperwallOptions/localResources`` and
+/// served to the paywall webview via the `swlocal://` URL scheme.
+///
+/// Conforming types:
+/// - `URL` — a file on disk.
+/// - `UIImage` — re-encoded as PNG when served to the webview. Use this to
+///   register an asset catalog Image Set: `UIImage(named: "Logo")!`.
+///
+/// ```swift
+/// options.localResources = [
+///   "hero-image": Bundle.main.url(forResource: "hero", withExtension: "png")!,
+///   "logo":       UIImage(named: "Logo")!
+/// ]
+/// ```
+public protocol AssetResource {}
+
+extension URL: AssetResource {}
+
+#if canImport(UIKit)
+extension UIImage: AssetResource {}
+#endif

Sources/SuperwallKit/Config/Options/SuperwallOptions.swift

@@ -4,38 +4,79 @@
 //
 //  Created by Yusuf Tör on 11/07/2022.
 //
+// swiftlint:disable file_length
 
 import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
 
 /// Options for configuring Superwall, including paywall presentation and appearance.
 ///
 /// Pass an instance of this class to
 /// ``Superwall/configure(apiKey:purchaseController:options:completion:)-52tke``.
+// swiftlint:disable type_body_length
 @objc(SWKSuperwallOptions)
 @objcMembers
 public final class SuperwallOptions: NSObject, Encodable {
   /// Configures the appearance and behaviour of paywalls.
   public var paywalls = PaywallOptions()
 
-  /// A mapping of local resource IDs to local file URLs.
+  /// A mapping of local resource IDs to ``AssetResource`` values.
   ///
-  /// Use this to serve paywall assets (images, videos, Lottie animations) from local files
-  /// instead of fetching them over the network. When a paywall references a `localResourceId`,
-  /// the SDK will look up the corresponding URL in this dictionary and serve the file via the
-  /// `swlocal://` URL scheme.
+  /// Use this to serve paywall assets (images, videos, Lottie animations) from the app
+  /// bundle or an asset catalog instead of fetching them over the network. When a paywall
+  /// references a `localResourceId`, the SDK looks up the corresponding entry here and
+  /// serves it via the `swlocal://` URL scheme.
+  ///
+  /// `URL` conforms to ``AssetResource`` so file-URL call sites keep working. Register an
+  /// `.xcassets` Image Set by passing a `UIImage`.
   ///
   /// Set this before calling ``Superwall/configure(apiKey:purchaseController:options:completion:)-52tke``
   /// to ensure resources are available before any paywall can trigger (e.g. on `app_launch`).
   ///
   /// ```swift
   /// let options = SuperwallOptions()
   /// options.localResources = [
-  ///   "hero-video": Bundle.main.url(forResource: "onboarding", withExtension: "mp4")!,
+  ///   "logo":       UIImage(named: "Logo")!,
   ///   "hero-image": Bundle.main.url(forResource: "hero", withExtension: "png")!
   /// ]
   /// Superwall.configure(apiKey: "your-api-key", options: options)
   /// ```
-  public var localResources: [String: URL] = [:]
+  @nonobjc public var localResources: [String: AssetResource] = [:]
+
+  /// Objective-C bridge for ``localResources``. Accepts `NSURL` and `UIImage` values
+  /// (mirroring the Swift surface); any other value type is dropped.
+  @available(swift, obsoleted: 1.0)
+  @objc(localResources)
+  public var localResourcesObjC: [String: NSObject] {
+    get {
+      return localResources.compactMapValues { resource in
+        if let url = resource as? URL {
+          return url as NSURL
+        }
+        #if canImport(UIKit)
+        if let image = resource as? UIImage {
+          return image
+        }
+        #endif
+        return nil
+      }
+    }
+    set {
+      localResources = newValue.compactMapValues { value in
+        if let url = value as? URL {
+          return url
+        }
+        #if canImport(UIKit)
+        if let image = value as? UIImage {
+          return image
+        }
+        #endif
+        return nil
+      }
+    }
+  }
 
   /// Controls when the SDK enters test mode.
   @objc(SWKTestModeBehavior)

Sources/SuperwallKit/Debug/SWLocalResourcesViewController.swift

@@ -7,7 +7,7 @@ import UIKit
 import AVFoundation
 
 final class SWLocalResourcesViewController: UICollectionViewController {
-  private var resources: [(id: String, url: URL)] = []
+  private var resources: [(id: String, resource: AssetResource)] = []
 
   init() {
     let layout = UICollectionViewFlowLayout()
@@ -53,7 +53,7 @@ final class SWLocalResourcesViewController: UICollectionViewController {
 
     resources = Superwall.shared.options.localResources
       .sorted { $0.key < $1.key }
-      .map { (id: $0.key, url: $0.value) }
+      .map { (id: $0.key, resource: $0.value) }
   }
 
   @objc private func doneTapped() {
@@ -86,7 +86,7 @@ final class SWLocalResourcesViewController: UICollectionViewController {
     // swiftlint:disable:next force_cast
     ) as! LocalResourceCell
     let resource = resources[indexPath.item]
-    cell.configure(id: resource.id, url: resource.url)
+    cell.configure(id: resource.id, resource: resource.resource)
     return cell
   }
 }
@@ -231,7 +231,20 @@ private final class LocalResourceCell: UICollectionViewCell {
     spinner.stopAnimating()
   }
 
-  func configure(id: String, url: URL) {
+  func configure(id: String, resource: AssetResource) {
+    if let url = resource as? URL {
+      configureURL(id: id, url: url)
+    } else if let image = resource as? UIImage {
+      idLabel.text = "\(id) (UIImage)"
+      spinner.stopAnimating()
+      imageView.image = image
+    } else {
+      idLabel.text = id
+      showErrorText("Unsupported resource type")
+    }
+  }
+
+  private func configureURL(id: String, url: URL) {
     let ext = url.pathExtension.lowercased()
     idLabel.text = ext.isEmpty ? id : "\(id).\(ext)"
     spinner.startAnimating()

Sources/SuperwallKit/Dependencies/DependencyContainer.swift

@@ -48,11 +48,13 @@ final class DependencyContainer {
   let paywallArchiveManager = PaywallArchiveManager()
 
   init(
+    apiKey: String = "",
     purchaseController controller: PurchaseController? = nil,
     options: SuperwallOptions? = nil
   ) {
     delegateAdapter = SuperwallDelegateAdapter()
     storage = Storage(factory: self)
+    storage.configure(apiKey: apiKey)
     entitlementsInfo = EntitlementsInfo(
       storage: storage,
       delegateAdapter: delegateAdapter
@@ -312,7 +314,8 @@ extension DependencyContainer: ViewControllerFactory {
       webView: webView,
       webEntitlementRedeemer: webEntitlementRedeemer,
       cache: cache,
-      paywallArchiveManager: paywallArchiveManager
+      paywallArchiveManager: paywallArchiveManager,
+      customCallbackRegistry: customCallbackRegistry
     )
 
     webView.delegate = paywallViewController

Sources/SuperwallKit/Graveyard/SuperwallGraveyard.swift

@@ -107,7 +107,8 @@ extension Superwall {
       ),
       webEntitlementRedeemer: dependencyContainer.webEntitlementRedeemer,
       cache: dependencyContainer.makeCache(),
-      paywallArchiveManager: dependencyContainer.paywallArchiveManager
+      paywallArchiveManager: dependencyContainer.paywallArchiveManager,
+      customCallbackRegistry: dependencyContainer.customCallbackRegistry
     )
   }
 

Sources/SuperwallKit/Identity/Email.swift

@@ -0,0 +1,32 @@
+//
+//  Email.swift
+//  SuperwallKit
+//
+
+import Foundation
+
+/// A validated email address.
+///
+/// The failable initializer rejects any string that does not match the
+/// pattern expected by the checkout API (`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z`).
+/// Holding an `Email` instance proves the value was validated — downstream
+/// code never needs to re-check.
+struct Email: Equatable, Sendable {
+  let rawValue: String
+
+  // `\z` (not `$`) is used so that a trailing `\n` is rejected — ICU treats `$`
+  // as matching at end-of-string *or* just before a final newline.
+  // Pattern is a validated literal — initialization can never throw at runtime.
+  private static let regex = try! NSRegularExpression( // swiftlint:disable:this force_try
+    pattern: #"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z"#
+  )
+
+  /// Returns `nil` when `rawValue` is not a syntactically valid email address.
+  init?(_ rawValue: String) {
+    let range = NSRange(rawValue.startIndex..., in: rawValue)
+    guard Self.regex.firstMatch(in: rawValue, range: range) != nil else {
+      return nil
+    }
+    self.rawValue = rawValue
+  }
+}

Sources/SuperwallKit/Identity/UserAttributes.swift

@@ -94,11 +94,39 @@ extension Superwall {
           continue
         }
         if JSONSerialization.isValidJSONObject([key: value]) {
-          customAttributes[key] = value
+          customAttributes[key] = Self.sanitizeAttribute(key: key, value: value)
         }
       }
     }
 
     dependencyContainer.identityManager.mergeUserAttributes(customAttributes)
   }
+
+  /// Validates attribute values that have server-side schema constraints.
+  ///
+  /// The checkout API rejects `context.identity.email` unless it is either a
+  /// valid email address or `null`. Apps that set a placeholder like `"none"`
+  /// would silently break the Stripe checkout flow, so the SDK parses the
+  /// value through ``Email`` and drops it when invalid.
+  private static func sanitizeAttribute(key: String, value: Any?) -> Any? {
+    guard let stringValue = value as? String else {
+      return value
+    }
+
+    switch key {
+    case "email":
+      guard let email = Email(stringValue) else {
+        Logger.debug(
+          logLevel: .warn,
+          scope: .identityManager,
+          message: "Invalid email user attribute — sending null to server"
+        )
+        return nil
+      }
+      return email.rawValue
+
+    default:
+      return value
+    }
+  }
 }

Sources/SuperwallKit/Misc/Constants.swift

@@ -18,5 +18,5 @@ let sdkVersion = """
 */
 
 let sdkVersion = """
-4.15.0
+4.15.1
 """