@npaw/forge-react-native 9.6.1 → 9.7.0

package/android/build.gradle

@@ -28,7 +28,7 @@ def safeExtGet(prop, fallback) {
 // FORGE_CORE_VERSION (see scripts/react-native/hydrate-natives.sh).
 def forgeCoreVersion = project.hasProperty('NpawForge_forgeCoreVersion')
     ? project.property('NpawForge_forgeCoreVersion')
-    : (System.getenv('FORGE_CORE_VERSION') ?: '9.6.1')
+    : (System.getenv('FORGE_CORE_VERSION') ?: '9.7.0')
 
 android {
     namespace 'com.npaw.forge.reactnative'

package/ios/ForgeApple/ForgeKernelFFI.xcframework/Info.plist

@@ -10,15 +10,18 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>tvos-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>libForgeKernelFFI.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
-			<string>tvos</string>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
@@ -26,7 +29,7 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>tvos-arm64</string>
 			<key>LibraryPath</key>
 			<string>libForgeKernelFFI.a</string>
 			<key>SupportedArchitectures</key>
@@ -34,7 +37,7 @@
 				<string>arm64</string>
 			</array>
 			<key>SupportedPlatform</key>
-			<string>ios</string>
+			<string>tvos</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
@@ -42,16 +45,15 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>tvos-arm64-simulator</string>
 			<key>LibraryPath</key>
 			<string>libForgeKernelFFI.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
-			<string>ios</string>
+			<string>tvos</string>
 			<key>SupportedPlatformVariant</key>
 			<string>simulator</string>
 		</dict>
@@ -61,7 +63,7 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>tvos-arm64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>libForgeKernelFFI.a</string>
 			<key>SupportedArchitectures</key>
@@ -69,9 +71,7 @@
 				<string>arm64</string>
 			</array>
 			<key>SupportedPlatform</key>
-			<string>tvos</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
+			<string>ios</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/ForgeApple/Sources/ForgeKernelUniFFI/forge_kernel.swift

@@ -1891,11 +1891,13 @@ public struct AppleRuntimeConfig: Equatable, Hashable {
     public var analyticsUserAgent: String?
     public var allowLocalHttp: Bool
     public var logLevel: String
+    public var deviceUuid: String?
+    public var deviceInfoJson: String?
     public var preSessionEventPolicy: ApplePreSessionEventPolicy
 
     // Default memberwise initializers are never public by default, so we
     // declare one manually.
-    public init(accountCode: String, pluginVersion: String, appName: String, buildVariant: String, appReleaseVersion: String?, lmaEndpoint: String, analyticsUserAgent: String?, allowLocalHttp: Bool, logLevel: String, preSessionEventPolicy: ApplePreSessionEventPolicy) {
+    public init(accountCode: String, pluginVersion: String, appName: String, buildVariant: String, appReleaseVersion: String?, lmaEndpoint: String, analyticsUserAgent: String?, allowLocalHttp: Bool, logLevel: String, deviceUuid: String?, deviceInfoJson: String?, preSessionEventPolicy: ApplePreSessionEventPolicy) {
         self.accountCode = accountCode
         self.pluginVersion = pluginVersion
         self.appName = appName
@@ -1905,6 +1907,8 @@ public struct AppleRuntimeConfig: Equatable, Hashable {
         self.analyticsUserAgent = analyticsUserAgent
         self.allowLocalHttp = allowLocalHttp
         self.logLevel = logLevel
+        self.deviceUuid = deviceUuid
+        self.deviceInfoJson = deviceInfoJson
         self.preSessionEventPolicy = preSessionEventPolicy
     }
 
@@ -1933,6 +1937,8 @@ public struct FfiConverterTypeAppleRuntimeConfig: FfiConverterRustBuffer {
                 analyticsUserAgent: FfiConverterOptionString.read(from: &buf), 
                 allowLocalHttp: FfiConverterBool.read(from: &buf), 
                 logLevel: FfiConverterString.read(from: &buf), 
+                deviceUuid: FfiConverterOptionString.read(from: &buf), 
+                deviceInfoJson: FfiConverterOptionString.read(from: &buf), 
                 preSessionEventPolicy: FfiConverterTypeApplePreSessionEventPolicy.read(from: &buf)
         )
     }
@@ -1947,6 +1953,8 @@ public struct FfiConverterTypeAppleRuntimeConfig: FfiConverterRustBuffer {
         FfiConverterOptionString.write(value.analyticsUserAgent, into: &buf)
         FfiConverterBool.write(value.allowLocalHttp, into: &buf)
         FfiConverterString.write(value.logLevel, into: &buf)
+        FfiConverterOptionString.write(value.deviceUuid, into: &buf)
+        FfiConverterOptionString.write(value.deviceInfoJson, into: &buf)
         FfiConverterTypeApplePreSessionEventPolicy.write(value.preSessionEventPolicy, into: &buf)
     }
 }

package/ios/ForgeApple/Sources/NPAWForgeCore/DeviceIdentity.swift

@@ -0,0 +1,194 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Automatic Apple device identity (deviceInfo fields and persistent deviceUUID) for Forge analytics.
+ */
+import Foundation
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// Device identity facts reported through the `deviceInfo` analytics parameter.
+///
+/// The JSON key names are a wire contract fixed by the v7 plugins, because the
+/// NQS device resolver reads those exact names. Note `deviceType`/`deviceCode`
+/// keep their prefix while `model`/`brand`/`osName`/`osVersion` do not, and
+/// vendor is `brand` — `deviceVendor` is the backend's column name and has
+/// never been a wire key.
+public struct ForgeDeviceInfo: Equatable {
+    public var brand: String?
+    public var code: String?
+    public var model: String?
+    public var type: String?
+    public var name: String?
+    public var osName: String?
+    public var osVersion: String?
+
+    public init(
+        brand: String? = nil,
+        code: String? = nil,
+        model: String? = nil,
+        type: String? = nil,
+        name: String? = nil,
+        osName: String? = nil,
+        osVersion: String? = nil
+    ) {
+        self.brand = brand
+        self.code = code
+        self.model = model
+        self.type = type
+        self.name = name
+        self.osName = osName
+        self.osVersion = osVersion
+    }
+
+    /// Ordered non-blank fields keyed by the `deviceInfo` JSON key names.
+    /// Blank values are omitted rather than sent empty, matching v7.
+    public func orderedFields() -> [(String, String)] {
+        var fields: [(String, String)] = []
+        func append(_ key: String, _ value: String?) {
+            guard let value, !value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                return
+            }
+            fields.append((key, value))
+        }
+        append("model", model)
+        append("osVersion", osVersion)
+        append("brand", brand)
+        append("deviceType", type)
+        append("deviceCode", code)
+        append("deviceName", name)
+        append("osName", osName)
+        return fields
+    }
+
+    public var isEmpty: Bool { orderedFields().isEmpty }
+
+    /// Serializes to the JSON object string the kernel expects. Returns `nil`
+    /// when no fact is known, so the param stays off the wire entirely.
+    public func toRuntimeJson() -> String? {
+        let fields = orderedFields()
+        guard !fields.isEmpty else { return nil }
+        let body = fields
+            .map { "\(Self.quoted($0.0)):\(Self.quoted($0.1))" }
+            .joined(separator: ",")
+        return "{\(body)}"
+    }
+
+    private static func quoted(_ value: String) -> String {
+        var escaped = ""
+        for character in value.unicodeScalars {
+            switch character {
+            case "\"": escaped.append("\\\"")
+            case "\\": escaped.append("\\\\")
+            case "\n": escaped.append("\\n")
+            case "\r": escaped.append("\\r")
+            case "\t": escaped.append("\\t")
+            default:
+                if character.value < 0x20 {
+                    escaped.append(String(format: "\\u%04x", character.value))
+                } else {
+                    escaped.unicodeScalars.append(character)
+                }
+            }
+        }
+        return "\"\(escaped)\""
+    }
+}
+
+public enum DeviceIdentity {
+    public static let deviceUuidStorageKey = "npaw_forge_device_uuid"
+
+    /// Collects the automatic device facts available on this platform.
+    ///
+    /// Matches the v7 iOS plugin where it reports at all — `brand` is the
+    /// literal `Apple` and `osVersion` comes from the system — and adds the
+    /// two facts v7 left to the backend's User-Agent parsing: `osName` and the
+    /// hardware `model`. That addition is deliberate. Forge's analytics
+    /// User-Agent is `NPAWForgeApple/<version> (<app>; <variant>)`, which
+    /// carries no device identity at all, unlike v7's
+    /// `<app>/<version>/<UIDevice.model>/<hw.machine>/<systemVersion>`. Without
+    /// these two fields NPAW would have no way to resolve an Apple device.
+    ///
+    /// `deviceType` is deliberately not inferred: v7 iOS emits no type literal
+    /// and the backend vocabulary is not ours to invent. Integrators can still
+    /// set it explicitly.
+    public static func collectDeviceInfo() -> ForgeDeviceInfo {
+        ForgeDeviceInfo(
+            brand: "Apple",
+            model: hardwareModel(),
+            osName: systemName(),
+            osVersion: systemVersion()
+        )
+    }
+
+    /// The hardware identifier, e.g. `iPhone16,1` or `AppleTV11,1`. This is the
+    /// same value v7 embedded in its User-Agent via `sysctlbyname("hw.machine")`.
+    /// On the simulator it reports the host architecture, which is expected.
+    public static func hardwareModel() -> String? {
+        var systemInfo = utsname()
+        uname(&systemInfo)
+        let machine = withUnsafePointer(to: &systemInfo.machine) { pointer in
+            pointer.withMemoryRebound(to: CChar.self, capacity: MemoryLayout.size(ofValue: pointer.pointee)) {
+                String(validatingUTF8: $0)
+            }
+        }
+        guard let machine, !machine.isEmpty else { return nil }
+        return machine
+    }
+
+    private static func systemName() -> String? {
+        #if os(tvOS)
+        return "tvOS"
+        #elseif os(visionOS)
+        return "visionOS"
+        #elseif os(watchOS)
+        return "watchOS"
+        #elseif os(macOS)
+        return "macOS"
+        #else
+        return "iOS"
+        #endif
+    }
+
+    private static func systemVersion() -> String? {
+        #if canImport(UIKit)
+        let version = UIDevice.current.systemVersion
+        return version.isEmpty ? nil : version
+        #else
+        let version = ProcessInfo.processInfo.operatingSystemVersion
+        return "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
+        #endif
+    }
+
+    /// Returns a stable device identifier.
+    ///
+    /// Prefers `identifierForVendor`, which is what v7 sends and what NPAW
+    /// already associates with Apple installs. When it is unavailable — it can
+    /// be `nil` before first unlock, and does not exist off UIKit — falls back
+    /// to a random UUID persisted in [storage], so a device is never left
+    /// without an identifier.
+    public static func persistentDeviceUuid(storage: ForgeStorage) -> String {
+        #if canImport(UIKit)
+        if let vendorId = UIDevice.current.identifierForVendor?.uuidString, !vendorId.isEmpty {
+            return vendorId
+        }
+        #endif
+        if let stored = storage.read(deviceUuidStorageKey),
+           !stored.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return stored
+        }
+        let generated = UUID().uuidString
+        _ = storage.write(deviceUuidStorageKey, value: generated)
+        return generated
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeApple.swift

@@ -28,6 +28,8 @@ public struct ForgeAppleConfig: Equatable {
     public var preSessionEventQueueLimitEvents: Int
     public var preSessionEventQueueMaxAgeMs: Int64
     public var logLevel: ForgeLogLevel
+    public var deviceUuid: String?
+    public var deviceInfo: ForgeDeviceInfo?
 
     public init(
         accountCode: String,
@@ -42,7 +44,9 @@ public struct ForgeAppleConfig: Equatable {
         processEventsBeforeSessionStart: Bool = false,
         preSessionEventQueueLimitEvents: Int = 100,
         preSessionEventQueueMaxAgeMs: Int64 = 30_000,
-        logLevel: ForgeLogLevel = .warning
+        logLevel: ForgeLogLevel = .warning,
+        deviceUuid: String? = nil,
+        deviceInfo: ForgeDeviceInfo? = nil
     ) {
         self.accountCode = accountCode
         self.pluginVersion = pluginVersion
@@ -57,6 +61,8 @@ public struct ForgeAppleConfig: Equatable {
         self.preSessionEventQueueLimitEvents = preSessionEventQueueLimitEvents
         self.preSessionEventQueueMaxAgeMs = preSessionEventQueueMaxAgeMs
         self.logLevel = logLevel
+        self.deviceUuid = deviceUuid
+        self.deviceInfo = deviceInfo
     }
 }
 

package/ios/ForgeApple/Sources/NPAWForgeCore/NPAWForge.swift

@@ -40,7 +40,7 @@ public final class NPAWForge: NSObject {
     /// `scripts/apple/publish-local-shipped.sh` rewrites this literal to the
     /// release version when staging the shipped package, and fails loudly if
     /// it cannot find it. Keep it a plain stored literal for that reason.
-    public static let defaultPluginVersion = "9.6.1"
+    public static let defaultPluginVersion = "9.7.0"
     public static let defaultAppName = "apple"
     public static let defaultBuildVariant = "release"
     public static let defaultLmaEndpoint = "https://lma.npaw.com"
@@ -298,6 +298,9 @@ public final class NPAWForge: NSObject {
         private var preSessionEventQueueLimitEvents = 100
         private var preSessionEventQueueMaxAgeMs: Int64 = 30_000
         private var logLevel: ForgeLogLevel = .warning
+        private var autoDeviceIdentityEnabled = true
+        private var deviceUuid: String?
+        private var deviceInfo: ForgeDeviceInfo?
         private var services: ForgeAppleServices?
 
         public init(accountCode: String) {
@@ -378,7 +381,40 @@ public final class NPAWForge: NSObject {
             return self
         }
 
+        /// Disables the automatic device identity collection (`deviceInfo` from
+        /// the system plus the `deviceUUID`). `deviceUUID` is a persistent
+        /// identifier, so integrators can opt out; an explicit
+        /// ``setDeviceUuid(_:)`` value is still honored when disabled.
+        @discardableResult
+        public func setAutoDeviceIdentityEnabled(_ enabled: Bool) -> Builder {
+            autoDeviceIdentityEnabled = enabled
+            return self
+        }
+
+        /// Overrides the automatically collected device identifier.
+        @discardableResult
+        public func setDeviceUuid(_ value: String?) -> Builder {
+            deviceUuid = value
+            return self
+        }
+
+        /// Overrides the automatically collected `deviceInfo` facts wholesale.
+        @discardableResult
+        public func setDeviceInfo(_ value: ForgeDeviceInfo?) -> Builder {
+            deviceInfo = value
+            return self
+        }
+
         public func build() -> NPAWForge {
+            // Services first: resolving the device UUID needs the storage the
+            // integrator supplied, so it cannot wait until after the config.
+            let resolvedServices = services ?? ForgeAppleServices(storage: UserDefaultsStorage())
+            let resolvedDeviceUuid = deviceUuid ?? (autoDeviceIdentityEnabled
+                ? DeviceIdentity.persistentDeviceUuid(storage: resolvedServices.storage)
+                : nil)
+            let resolvedDeviceInfo = deviceInfo ?? (autoDeviceIdentityEnabled
+                ? DeviceIdentity.collectDeviceInfo()
+                : nil)
             let config = ForgeAppleConfig(
                 accountCode: accountCode,
                 pluginVersion: NPAWForge.defaultPluginVersion,
@@ -392,9 +428,10 @@ public final class NPAWForge: NSObject {
                 processEventsBeforeSessionStart: processEventsBeforeSessionStart,
                 preSessionEventQueueLimitEvents: preSessionEventQueueLimitEvents,
                 preSessionEventQueueMaxAgeMs: preSessionEventQueueMaxAgeMs,
-                logLevel: logLevel
+                logLevel: logLevel,
+                deviceUuid: resolvedDeviceUuid,
+                deviceInfo: resolvedDeviceInfo?.isEmpty == true ? nil : resolvedDeviceInfo
             )
-            let resolvedServices = services ?? ForgeAppleServices(storage: UserDefaultsStorage())
             let forge = NPAWForge(kernel: ForgeApple(config: config, services: resolvedServices))
             ForgeAutomaticCaptureRegistry.installIfAvailable(forge)
             return forge

package/ios/ForgeApple/Sources/NPAWForgeCore/NativeUniFFIRuntime.swift

@@ -38,6 +38,8 @@ final class UniFFIForgeRuntime: ForgeRuntime {
             analyticsUserAgent: config.analyticsUserAgent,
             allowLocalHttp: config.allowLocalHttp,
             logLevel: config.logLevel.wireName,
+            deviceUuid: config.deviceUuid,
+            deviceInfoJson: config.deviceInfo?.toRuntimeJson(),
             preSessionEventPolicy: ApplePreSessionEventPolicy(
                 processEventsBeforeSessionStart: config.processEventsBeforeSessionStart,
                 queueLimitEvents: UInt64(max(0, config.preSessionEventQueueLimitEvents)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npaw/forge-react-native",
-  "version": "9.6.1",
+  "version": "9.7.0",
   "description": "NPAW Forge analytics for React Native: New Architecture TurboModule facade over the native Forge Android/Apple SDKs.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Victor Soto <victor.soto@nicepeopleatwork.com>",