@apex-inc/capacitor-plugin 2.4.1 → 2.5.0

package/ios/Sources/ApexCapacitorPlugin/SkanManager.swift

@@ -5,8 +5,10 @@
 //  Wraps SKAdNetwork conversion value updates.
 //
 //  - SKAN 3.0 (iOS 11.3-14.x): `SKAdNetwork.updateConversionValue(Int)` — fine value 0-63.
-//  - SKAN 4.0 (iOS 16.1+): `SKAdNetwork.updatePostbackConversionValue(_:coarseValue:completionHandler:)`
-//    — fine value 0-63 plus optional coarse value (`.low`, `.medium`, `.high`).
+//  - SKAN 4.0 (iOS 16.1+): `SKAdNetwork.updatePostbackConversionValue(_:coarseValue:lockWindow:completionHandler:)`
+//    — fine value 0-63 plus optional coarse value (`.low`, `.medium`, `.high`)
+//    and an optional `lockWindow` that asks Apple to send the current
+//    window's postback without waiting the window out.
 //
 //  The class validates inputs (0-63 fine) and routes to the correct API
 //  based on iOS availability and whether a coarse value is provided.
@@ -45,6 +47,7 @@ public final class SkanManager {
     public func update(
         fineValue: Int,
         coarseValue: SkanCoarseValue? = nil,
+        lockWindow: Bool = false,
         completion: @escaping (Error?) -> Void
     ) {
         do {
@@ -53,7 +56,12 @@ public final class SkanManager {
             completion(error)
             return
         }
-        updater.updateConversionValue(fineValue: fineValue, coarseValue: coarseValue, completion: completion)
+        updater.updateConversionValue(
+            fineValue: fineValue,
+            coarseValue: coarseValue,
+            lockWindow: lockWindow,
+            completion: completion
+        )
     }
 }
 
@@ -61,6 +69,7 @@ public protocol SkanUpdaterProtocol {
     func updateConversionValue(
         fineValue: Int,
         coarseValue: SkanCoarseValue?,
+        lockWindow: Bool,
         completion: @escaping (Error?) -> Void
     )
 }
@@ -71,6 +80,7 @@ public final class DefaultSkanUpdater: SkanUpdaterProtocol {
     public func updateConversionValue(
         fineValue: Int,
         coarseValue: SkanCoarseValue?,
+        lockWindow: Bool,
         completion: @escaping (Error?) -> Void
     ) {
         if let coarse = coarseValue, #available(iOS 16.1, *) {
@@ -80,7 +90,11 @@ public final class DefaultSkanUpdater: SkanUpdaterProtocol {
             case .medium: apiCoarse = .medium
             case .high: apiCoarse = .high
             }
-            SKAdNetwork.updatePostbackConversionValue(fineValue, coarseValue: apiCoarse) { error in
+            SKAdNetwork.updatePostbackConversionValue(
+                fineValue,
+                coarseValue: apiCoarse,
+                lockWindow: lockWindow
+            ) { error in
                 completion(error)
             }
         } else if #available(iOS 15.4, *) {

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -116,7 +116,10 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         defaults.set(visitorId, forKey: "apex.visitorId")
 
         deepLinks.setWarmLinkHandler { [weak self] url in
-            self?.notifyListeners("deepLink", data: ["url": url.absoluteString])
+            self?.notifyListeners("deepLink", data: [
+                "url": url.absoluteString,
+                "deepLinkHint": DeepLinkManager.apexHint(from: url) ?? NSNull(),
+            ])
         }
 
         // MMP-177 — observe foreground pushes posted by the app's
@@ -514,8 +517,10 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     }
 
     @objc public func getInstallReferrer(_ call: CAPPluginCall) {
-        // iOS has no equivalent of Play Install Referrer.
-        call.resolve(["referrer": NSNull()])
+        // iOS has no equivalent of Play Install Referrer: the App Store
+        // forwards nothing across an install, so deferred deep linking
+        // here falls back to the probabilistic server match.
+        call.resolve(["referrer": NSNull(), "clickTimestamp": 0])
     }
 
     @objc public func getVisitorId(_ call: CAPPluginCall) {
@@ -618,7 +623,8 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         if let raw = call.getString("coarseValue") {
             coarse = SkanCoarseValue(rawValue: raw)
         }
-        skanManager.update(fineValue: fineValue, coarseValue: coarse) { error in
+        let lockWindow = call.getBool("lockWindow") ?? false
+        skanManager.update(fineValue: fineValue, coarseValue: coarse, lockWindow: lockWindow) { error in
             if let error = error {
                 call.reject("SKAN update failed: \(error.localizedDescription)")
             } else {
@@ -631,9 +637,12 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
 
     @objc public func getInitialDeepLink(_ call: CAPPluginCall) {
         if let url = deepLinks.consumeInitialUrl() {
-            call.resolve(["url": url.absoluteString])
+            call.resolve([
+                "url": url.absoluteString,
+                "deepLinkHint": DeepLinkManager.apexHint(from: url) ?? NSNull(),
+            ])
         } else {
-            call.resolve(["url": NSNull()])
+            call.resolve(["url": NSNull(), "deepLinkHint": NSNull()])
         }
     }
 
@@ -853,6 +862,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         request.setValue("sdk", forHTTPHeaderField: "x-apex-source")
         request.setValue(visitorId, forHTTPHeaderField: "x-apex-visitor-id")
         request.setValue(workspaceKey, forHTTPHeaderField: "x-apex-workspace")
+        request.setValue(releaseChannel, forHTTPHeaderField: "x-apex-release-channel")
         if let key = apiKey {
             request.setValue(key, forHTTPHeaderField: "x-apex-api-key")
         }
@@ -898,12 +908,18 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     /// mobile slot / testMode). Batched through the offline queue.
     private func enqueueExposure(experimentId: String, variant: String) {
         guard let queue = offlineQueue else { return }
+        // The app version that saw the variant — the mobile equivalent of the
+        // web build id. On mobile the experiment logic often ships inside the
+        // binary, so "which version was exposed" is what makes results honest
+        // during a staged rollout + enables version-gating (Phase 5, 2026-07-20).
+        let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0.0.0"
         var payload: [String: AnyCodable] = [:]
         payload["type"] = AnyCodable("experiment_exposure")
         payload["data"] = AnyCodable([
             "experiment_id": experimentId,
             "variant_key": variant,
             "surface": "mobile",
+            "app_version": appVersion,
         ])
         if testMode {
             payload["testMode"] = AnyCodable(true)

package/ios/Tests/ApexCapacitorPluginTests/DeepLinkManagerTests.swift

@@ -66,4 +66,30 @@ final class DeepLinkManagerTests: XCTestCase {
     func testIsValidDeepLinkRejectsFileUrl() {
         XCTAssertFalse(DeepLinkManager.isValidDeepLink(URL(string: "file:///tmp/test")!))
     }
+
+    func testApexHintReadsParam() {
+        let url = URL(string: "https://acme.example/summer?apex_dl=%2Foffers%2Fsummer")!
+        XCTAssertEqual(DeepLinkManager.apexHint(from: url), "/offers/summer")
+    }
+
+    func testApexHintFindsParamAmongOthers() {
+        let url = URL(
+            string: "https://acme.example/s?utm_source=linkedin&apex_dl=screen-42&utm_medium=social"
+        )!
+        XCTAssertEqual(DeepLinkManager.apexHint(from: url), "screen-42")
+    }
+
+    func testApexHintNilWhenAbsent() {
+        let url = URL(string: "https://acme.example/summer?utm_source=x")!
+        XCTAssertNil(DeepLinkManager.apexHint(from: url))
+    }
+
+    func testApexHintNilWithNoQuery() {
+        XCTAssertNil(DeepLinkManager.apexHint(from: URL(string: "https://acme.example/s")!))
+    }
+
+    func testApexHintNilWhenEmpty() {
+        let url = URL(string: "https://acme.example/s?apex_dl=")!
+        XCTAssertNil(DeepLinkManager.apexHint(from: url))
+    }
 }

package/ios/Tests/ApexCapacitorPluginTests/SkanManagerTests.swift

@@ -9,6 +9,7 @@ final class RecordingSkanUpdater: SkanUpdaterProtocol {
     struct Call: Equatable {
         let fineValue: Int
         let coarseValue: SkanCoarseValue?
+        let lockWindow: Bool
     }
     var calls: [Call] = []
     var nextError: Error?
@@ -16,9 +17,10 @@ final class RecordingSkanUpdater: SkanUpdaterProtocol {
     func updateConversionValue(
         fineValue: Int,
         coarseValue: SkanCoarseValue?,
+        lockWindow: Bool,
         completion: @escaping (Error?) -> Void
     ) {
-        calls.append(Call(fineValue: fineValue, coarseValue: coarseValue))
+        calls.append(Call(fineValue: fineValue, coarseValue: coarseValue, lockWindow: lockWindow))
         completion(nextError)
     }
 }
@@ -88,4 +90,23 @@ final class SkanManagerTests: XCTestCase {
         XCTAssertEqual(SkanCoarseValue.medium.rawValue, "medium")
         XCTAssertEqual(SkanCoarseValue.high.rawValue, "high")
     }
+
+    func testUpdatePassesLockWindowThrough() {
+        let updater = RecordingSkanUpdater()
+        let manager = SkanManager(updater: updater)
+        let exp = expectation(description: "update")
+        manager.update(fineValue: 32, coarseValue: .high, lockWindow: true) { _ in exp.fulfill() }
+        wait(for: [exp], timeout: 1)
+        XCTAssertEqual(updater.calls.count, 1)
+        XCTAssertTrue(updater.calls[0].lockWindow)
+    }
+
+    func testUpdateDefaultsLockWindowToFalse() {
+        let updater = RecordingSkanUpdater()
+        let manager = SkanManager(updater: updater)
+        let exp = expectation(description: "update")
+        manager.update(fineValue: 8, coarseValue: .medium) { _ in exp.fulfill() }
+        wait(for: [exp], timeout: 1)
+        XCTAssertFalse(updater.calls[0].lockWindow)
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/capacitor-plugin",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Apex Capacitor plugin — iOS/Android attribution, events, deep linking, SKAN, and offline-tolerant tracking for Capacitor apps.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",