@apex-inc/capacitor-plugin 2.5.0 → 2.6.0

package/ios/Sources/ApexCapacitorPlugin/FirstLaunchInstall.swift

@@ -0,0 +1,50 @@
+//
+//  FirstLaunchInstall.swift
+//  Apex Capacitor Plugin
+//
+//  Whether this launch should send `app_install`. The plugin sends it once
+//  per install so every app counts installs the same way; the app's own
+//  `app_install` is dropped once one has gone.
+//
+//  Someone who had the app before Apex was added is not a new install: the
+//  update that brings Apex must not report every existing user to the ad
+//  networks as one. A fresh install is one made in the last 7 days, or one
+//  never updated since (the version installed is the one running).
+//
+
+import Foundation
+
+public enum FirstLaunchInstall {
+    public static let defaultsKey = "apex.installSent"
+    public static let freshWindow: TimeInterval = 7 * 24 * 3600
+    private static let sameVersionTolerance: TimeInterval = 5 * 60
+
+    public enum Decision: Equatable { case send, alreadySent, existingUser }
+
+    public static func decide(
+        alreadySent: Bool,
+        installedAt: Date?,
+        versionInstalledAt: Date?,
+        now: Date
+    ) -> Decision {
+        if alreadySent { return .alreadySent }
+        guard let installedAt = installedAt else { return .send }
+        if let versionInstalledAt = versionInstalledAt,
+           abs(versionInstalledAt.timeIntervalSince(installedAt)) <= sameVersionTolerance {
+            return .send
+        }
+        return now.timeIntervalSince(installedAt) <= freshWindow ? .send : .existingUser
+    }
+
+    /// When the app was first installed: the Documents folder is made then
+    /// and survives updates.
+    public static func installedAt() -> Date? {
+        guard let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return nil }
+        return (try? FileManager.default.attributesOfItem(atPath: docs.path))?[.creationDate] as? Date
+    }
+
+    /// When the running version was installed: the app bundle is replaced on every update.
+    public static func versionInstalledAt() -> Date? {
+        (try? FileManager.default.attributesOfItem(atPath: Bundle.main.bundlePath))?[.creationDate] as? Date
+    }
+}

package/ios/Sources/ApexCapacitorPlugin/MobileContext.swift

@@ -0,0 +1,49 @@
+//
+//  MobileContext.swift
+//  Apex Capacitor Plugin
+//
+//  The device details stamped under `event.mobile` on every event. Apex
+//  builds the ad networks' app-event device block from them (Meta's
+//  `app_data` + `extinfo`), so an event without them reaches Meta with a
+//  blank device and tracking marked off.
+//
+//  The advertising id is the IDFA, and only when the person allowed
+//  tracking. The IDFV fallback is never sent: it is not an advertising id
+//  and Meta must not match on it.
+//
+
+import Foundation
+
+public enum MobileContext {
+    public static func fields(
+        device: DeviceMetadata,
+        att: AttStatus,
+        adId: AdvertisingIdResult
+    ) -> [String: Any] {
+        var fields: [String: Any] = [
+            "bundleId": device.bundleId,
+            "appVersion": device.appVersion,
+            "osVersion": device.osVersion,
+            "deviceModel": device.model,
+            "timezone": device.timezone,
+            "locale": device.locale,
+            "attStatus": att.rawValue,
+        ]
+        if att == .authorized, adId.fallback == nil, let idfa = adId.id {
+            fields["idfa"] = idfa
+        }
+        return fields
+    }
+
+    /// Fill the fields the caller didn't set on the event.
+    public static func fill(
+        _ slot: inout [String: Any],
+        device: DeviceMetadata,
+        att: AttStatus,
+        adId: AdvertisingIdResult
+    ) {
+        for (key, value) in fields(device: device, att: att, adId: adId) where slot[key] == nil {
+            slot[key] = value
+        }
+    }
+}

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
@@ -582,6 +639,9 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         if !traits.isEmpty {
             body["metadata"] = traits
         }
+        if let userHash = call.getString("userHash"), !userHash.isEmpty {
+            body["userHash"] = userHash
+        }
 
         var request = URLRequest(url: url)
         request.httpMethod = "POST"
@@ -927,10 +987,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(),
@@ -944,6 +1005,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")
@@ -955,6 +1027,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 }
@@ -1001,6 +1078,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         }
         mobileSlot["releaseChannel"] = releaseChannel
         mobileSlot["releaseChannelSource"] = releaseChannelSource
+        stampDevice(&mobileSlot)
         codablePayload["mobile"] = AnyCodable(mobileSlot)
         let event = NativeQueuedEvent(
             id: id,
@@ -1063,6 +1141,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.0",
+  "version": "2.6.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",
@@ -54,7 +54,10 @@
     "clean": "rimraf ./dist",
     "watch": "tsc --watch",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "node ../../scripts/product-update/assert.mjs && npm run build",
+    "postpublish": "node ../../scripts/product-update/notify.mjs",
+    "notify-product-update": "node ../../scripts/product-update/notify.mjs --send"
   },
   "devDependencies": {
     "@capacitor/core": "^7.0.0",

package/ios/Package.swift

@@ -1,34 +0,0 @@
-// swift-tools-version: 5.9
-//
-// This manifest builds the pure-logic portion of @apex-inc/capacitor-plugin
-// for standalone test runs via `swift test`. The Capacitor-dependent plugin
-// entry point (ApexCapacitorPlugin.swift) lives in a sibling folder and is
-// compiled only through the CocoaPods build path (see .podspec) because it
-// imports the Capacitor framework.
-//
-// Consumers installing the plugin in a Capacitor app get BOTH sources via
-// `npx cap sync` + CocoaPods — this split is purely a testability concern.
-//
-import PackageDescription
-
-let package = Package(
-    name: "ApexCapacitorPlugin",
-    platforms: [.iOS(.v14)],
-    products: [
-        .library(
-            name: "ApexCapacitorPlugin",
-            targets: ["ApexCapacitorPlugin"]
-        ),
-    ],
-    targets: [
-        .target(
-            name: "ApexCapacitorPlugin",
-            path: "Sources/ApexCapacitorPlugin"
-        ),
-        .testTarget(
-            name: "ApexCapacitorPluginTests",
-            dependencies: ["ApexCapacitorPlugin"],
-            path: "Tests/ApexCapacitorPluginTests"
-        ),
-    ]
-)