@apex-inc/capacitor-plugin 2.5.1 → 2.6.1

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -55,6 +55,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     private var attManager = AttManager()
     private var skanManager = SkanManager()
     private var deviceInfo = DeviceInfo()
+    private lazy var deviceMeta: DeviceMetadata = deviceInfo.collect()
     private var deepLinks = DeepLinkManager()
     private var adIds = AdvertisingIdProvider()
     private lazy var pushManager = PushNotificationManager()
@@ -101,6 +102,9 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     // Phase 4a — consent gate. Defaults granted; set false by
     // initialize({ requireConsent: true }) until setConsent({ granted:true }).
     private var consentGranted = true
+    // The install is sent once per install, by the plugin or the app, never both.
+    private var autoTrackInstall = true
+    private let installLock = NSLock()
     // Phase 3 — per-launch dedup so each (experiment, variant) exposure
     // fires once, matching the JS/web fallback.
     private var firedExposures = Set<String>()
@@ -216,6 +220,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         apiKey = rawKey.isEmpty ? nil : rawKey
         // Phase 4a — consent gate.
         consentGranted = !(call.getBool("requireConsent") ?? false)
+        autoTrackInstall = call.getBool("autoTrackInstall") ?? true
 
         // MMP-061 — release channel detection. iOS uses the receipt URL
         // + StoreKit 2 AppTransaction. Any JS-supplied override on iOS
@@ -271,10 +276,62 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             self?.handleTokenArrived(token)
         }
         pushManager.silentRegisterIfAuthorized()
+        sendInstallIfFirstLaunch()
 
         call.resolve()
     }
 
+    /// Send `app_install` on the first launch of a fresh install. Marks the
+    /// install as handled for someone who had the app before Apex, so the
+    /// update that adds Apex reports no one as new.
+    private func sendInstallIfFirstLaunch() {
+        guard autoTrackInstall, consentGranted, let queue = offlineQueue else { return }
+        let defaults = UserDefaults.standard
+        installLock.lock()
+        let decision = FirstLaunchInstall.decide(
+            alreadySent: defaults.bool(forKey: FirstLaunchInstall.defaultsKey),
+            installedAt: FirstLaunchInstall.installedAt(),
+            versionInstalledAt: FirstLaunchInstall.versionInstalledAt(),
+            now: Date()
+        )
+        if decision != .alreadySent { defaults.set(true, forKey: FirstLaunchInstall.defaultsKey) }
+        installLock.unlock()
+        if debug { print("[apex-capacitor] first-launch install: \(decision)") }
+        guard decision == .send else { return }
+
+        var payload: [String: AnyCodable] = [:]
+        payload["type"] = AnyCodable("app_install")
+        payload["data"] = AnyCodable(["source": "apex_first_launch"])
+        if testMode { payload["testMode"] = AnyCodable(true) }
+        payload["platform"] = AnyCodable("ios")
+        payload["timestamp"] = AnyCodable(ISO8601DateFormatter().string(from: Date()))
+        payload["visitorId"] = AnyCodable(visitorId)
+        var mobileSlot: [String: Any] = [
+            "releaseChannel": releaseChannel,
+            "releaseChannelSource": releaseChannelSource,
+        ]
+        stampDevice(&mobileSlot)
+        payload["mobile"] = AnyCodable(mobileSlot)
+        let event = NativeQueuedEvent(
+            id: UUID().uuidString.lowercased(),
+            payload: payload,
+            attempts: 0,
+            enqueuedAt: Date()
+        )
+        try? queue.enqueue(event)
+        kickFlush(reason: "track")
+    }
+
+    /// True the first time an install is claimed; the app's own `app_install` after that is dropped.
+    private func claimInstall() -> Bool {
+        installLock.lock()
+        defer { installLock.unlock() }
+        let defaults = UserDefaults.standard
+        if defaults.bool(forKey: FirstLaunchInstall.defaultsKey) { return false }
+        defaults.set(true, forKey: FirstLaunchInstall.defaultsKey)
+        return true
+    }
+
     /// Forward a freshly-arrived APNs device token to JS listeners and
     /// register it with the Apex backend. Shared by the explicit
     /// `registerForPushNotifications()` path and the silent re-register
@@ -552,12 +609,6 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     /// guarantees than firing a track event, and merchants tend to
     /// wire identify behind a one-shot boundary.
     @objc public func identify(_ call: CAPPluginCall) {
-        // Phase 4a — identify sends PII; collect nothing until consent given.
-        if !consentGranted {
-            if debug { print("[apex-capacitor] consent not granted; skipping identify") }
-            call.resolve()
-            return
-        }
         guard let email = call.getString("email")?.trimmingCharacters(in: .whitespaces),
               !email.isEmpty else {
             call.reject("email is required")
@@ -571,11 +622,19 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             return
         }
         var body: [String: Any] = [
-            "visitorId": visitorId,
             "email": email,
             "workspaceKey": workspaceKey,
             "timestamp": ISO8601DateFormatter().string(from: Date()),
         ]
+        // Signing up is its own reason to know the person. Without consent
+        // only the identify goes: no device id, and Apex records advertising
+        // as denied so no ad platform is sent them.
+        if consentGranted {
+            body["visitorId"] = visitorId
+        } else {
+            if debug { print("[apex-capacitor] consent not granted; identifying without a device id") }
+            body["noBrowserConsent"] = true
+        }
         if let userId = userId, !userId.isEmpty {
             body["userId"] = userId
         }
@@ -930,10 +989,11 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         payload["platform"] = AnyCodable("ios")
         payload["timestamp"] = AnyCodable(ISO8601DateFormatter().string(from: Date()))
         payload["visitorId"] = AnyCodable(visitorId)
-        let mobileSlot: [String: Any] = [
+        var mobileSlot: [String: Any] = [
             "releaseChannel": releaseChannel,
             "releaseChannelSource": releaseChannelSource,
         ]
+        stampDevice(&mobileSlot)
         payload["mobile"] = AnyCodable(mobileSlot)
         let event = NativeQueuedEvent(
             id: UUID().uuidString.lowercased(),
@@ -947,6 +1007,17 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
 
     // MARK: - Events & Queue
 
+    /// The device, the tracking answer, and the IDFA when the person allowed
+    /// it. Read per event: the answer can change in Settings mid-session.
+    private func stampDevice(_ slot: inout [String: Any]) {
+        MobileContext.fill(
+            &slot,
+            device: deviceMeta,
+            att: attManager.currentStatus(),
+            adId: adIds.current()
+        )
+    }
+
     @objc public func track(_ call: CAPPluginCall) {
         guard let queue = offlineQueue else {
             call.reject("Plugin not initialized — call initialize() first")
@@ -958,6 +1029,11 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             call.resolve()
             return
         }
+        if call.getString("type") == "app_install" && !claimInstall() {
+            if debug { print("[apex-capacitor] app_install already sent for this install; dropping") }
+            call.resolve()
+            return
+        }
 
         let id = call.getString("id") ?? UUID().uuidString.lowercased()
         let payloadDict = call.options.compactMapValues { $0 }
@@ -1004,6 +1080,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         }
         mobileSlot["releaseChannel"] = releaseChannel
         mobileSlot["releaseChannelSource"] = releaseChannelSource
+        stampDevice(&mobileSlot)
         codablePayload["mobile"] = AnyCodable(mobileSlot)
         let event = NativeQueuedEvent(
             id: id,
@@ -1066,6 +1143,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         if granted {
             // Resume: flush anything captured before this point.
             kickFlush(reason: "consent")
+            sendInstallIfFirstLaunch()
         } else {
             // Revoke: drop anything queued but not yet sent.
             try? offlineQueue?.clear()

package/ios/Sources/PrivacyInfo.xcprivacy

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  What @apex-inc/capacitor-plugin collects, merged by Xcode into the app's
+  privacy report. Installs and purchases count as tracking because Apex
+  sends them to the ad networks the app connects to measure ads. The IDFA
+  is read only after the person allows tracking in the ATT prompt. No
+  tracking domains are listed: iOS blocks listed domains
+  outright when tracking is denied, and Apex's own endpoint also serves
+  measurement that needs no permission.
+-->
+<plist version="1.0">
+<dict>
+	<key>NSPrivacyTracking</key>
+	<true/>
+	<key>NSPrivacyTrackingDomains</key>
+	<array/>
+	<key>NSPrivacyCollectedDataTypes</key>
+	<array>
+		<dict>
+			<key>NSPrivacyCollectedDataType</key>
+			<string>NSPrivacyCollectedDataTypeDeviceID</string>
+			<key>NSPrivacyCollectedDataTypeLinked</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypeTracking</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypePurposes</key>
+			<array>
+				<string>NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising</string>
+				<string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+			</array>
+		</dict>
+		<dict>
+			<key>NSPrivacyCollectedDataType</key>
+			<string>NSPrivacyCollectedDataTypeProductInteraction</string>
+			<key>NSPrivacyCollectedDataTypeLinked</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypeTracking</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypePurposes</key>
+			<array>
+				<string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+				<string>NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising</string>
+			</array>
+		</dict>
+		<dict>
+			<key>NSPrivacyCollectedDataType</key>
+			<string>NSPrivacyCollectedDataTypePurchaseHistory</string>
+			<key>NSPrivacyCollectedDataTypeLinked</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypeTracking</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypePurposes</key>
+			<array>
+				<string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+				<string>NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising</string>
+			</array>
+		</dict>
+	</array>
+	<key>NSPrivacyAccessedAPITypes</key>
+	<array>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>CA92.1</string>
+			</array>
+		</dict>
+	</array>
+</dict>
+</plist>

package/ios/Tests/ApexCapacitorPluginTests/FirstLaunchInstallTests.swift

@@ -0,0 +1,66 @@
+//
+//  FirstLaunchInstallTests.swift
+//
+
+import XCTest
+@testable import ApexCapacitorPlugin
+
+final class FirstLaunchInstallTests: XCTestCase {
+
+    private let now = Date(timeIntervalSince1970: 1_790_000_000)
+    private let day: TimeInterval = 24 * 3600
+
+    func testSendsOnTheFirstLaunchOfAFreshInstall() {
+        let installed = now.addingTimeInterval(-60)
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(alreadySent: false, installedAt: installed, versionInstalledAt: installed, now: now),
+            .send
+        )
+    }
+
+    func testSendsOnceOnly() {
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(alreadySent: true, installedAt: now, versionInstalledAt: now, now: now),
+            .alreadySent
+        )
+    }
+
+    func testAnUpdateThatAddsApexIsNotAnInstall() {
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(
+                alreadySent: false,
+                installedAt: now.addingTimeInterval(-90 * day),
+                versionInstalledAt: now.addingTimeInterval(-day),
+                now: now
+            ),
+            .existingUser
+        )
+    }
+
+    func testARecentInstallStillCountsAfterAQuickUpdate() {
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(
+                alreadySent: false,
+                installedAt: now.addingTimeInterval(-3 * day),
+                versionInstalledAt: now.addingTimeInterval(-day),
+                now: now
+            ),
+            .send
+        )
+    }
+
+    func testALateFirstOpenOfANeverUpdatedInstallCounts() {
+        let installed = now.addingTimeInterval(-20 * day)
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(alreadySent: false, installedAt: installed, versionInstalledAt: installed, now: now),
+            .send
+        )
+    }
+
+    func testSendsWhenTheInstallTimeIsUnknown() {
+        XCTAssertEqual(
+            FirstLaunchInstall.decide(alreadySent: false, installedAt: nil, versionInstalledAt: nil, now: now),
+            .send
+        )
+    }
+}

package/ios/Tests/ApexCapacitorPluginTests/MobileContextTests.swift

@@ -0,0 +1,56 @@
+//
+//  MobileContextTests.swift
+//
+
+import XCTest
+@testable import ApexCapacitorPlugin
+
+final class MobileContextTests: XCTestCase {
+
+    private let device = DeviceMetadata(
+        platform: "ios",
+        osVersion: "18.1",
+        model: "iPhone16,1",
+        appVersion: "3.1.0",
+        bundleId: "com.skillshot.app",
+        timezone: "America/Chicago",
+        locale: "en-US"
+    )
+
+    func testStampsTheDeviceAndTheIdfaWhenTrackingIsAllowed() {
+        let fields = MobileContext.fields(
+            device: device,
+            att: .authorized,
+            adId: AdvertisingIdResult(id: "6d92078a-8246-4ba4-ae5b-76104861e7dc", fallback: nil)
+        )
+        XCTAssertEqual(fields["bundleId"] as? String, "com.skillshot.app")
+        XCTAssertEqual(fields["deviceModel"] as? String, "iPhone16,1")
+        XCTAssertEqual(fields["attStatus"] as? String, "authorized")
+        XCTAssertEqual(fields["idfa"] as? String, "6d92078a-8246-4ba4-ae5b-76104861e7dc")
+    }
+
+    func testNeverSendsTheIdfvAsTheAdvertisingId() {
+        let fields = MobileContext.fields(
+            device: device,
+            att: .denied,
+            adId: AdvertisingIdResult(id: "idfv-value", fallback: "idfv")
+        )
+        XCTAssertNil(fields["idfa"])
+        XCTAssertNil(fields["idfv"])
+        XCTAssertEqual(fields["attStatus"] as? String, "denied")
+    }
+
+    func testKeepsWhatTheAppSet() {
+        var slot: [String: Any] = ["releaseChannel": "app-store", "locale": "fr-FR"]
+        MobileContext.fill(
+            &slot,
+            device: device,
+            att: .notDetermined,
+            adId: AdvertisingIdResult(id: nil, fallback: nil)
+        )
+        XCTAssertEqual(slot["locale"] as? String, "fr-FR")
+        XCTAssertEqual(slot["releaseChannel"] as? String, "app-store")
+        XCTAssertEqual(slot["appVersion"] as? String, "3.1.0")
+        XCTAssertEqual(slot["attStatus"] as? String, "not-determined")
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/capacitor-plugin",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "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",