@npaw/forge-react-native 9.7.1 → 9.7.3

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

@@ -30,6 +30,10 @@ public struct ForgeAppleConfig: Equatable {
     public var logLevel: ForgeLogLevel
     public var deviceUuid: String?
     public var deviceInfo: ForgeDeviceInfo?
+    /// Framework layered on top of this facade, when one applies. Set by
+    /// first-party bindings only - React Native declares itself here so its
+    /// traffic is distinguishable in `pluginInfo`. The platform stays `apple`.
+    public var framework: String?
 
     public init(
         accountCode: String,
@@ -46,7 +50,8 @@ public struct ForgeAppleConfig: Equatable {
         preSessionEventQueueMaxAgeMs: Int64 = 30_000,
         logLevel: ForgeLogLevel = .warning,
         deviceUuid: String? = nil,
-        deviceInfo: ForgeDeviceInfo? = nil
+        deviceInfo: ForgeDeviceInfo? = nil,
+        framework: String? = nil
     ) {
         self.accountCode = accountCode
         self.pluginVersion = pluginVersion
@@ -63,6 +68,7 @@ public struct ForgeAppleConfig: Equatable {
         self.logLevel = logLevel
         self.deviceUuid = deviceUuid
         self.deviceInfo = deviceInfo
+        self.framework = framework
     }
 }
 
@@ -140,6 +146,7 @@ public final class ForgeApple {
     private var onSendRequestListeners: [UUID: (String, inout [String: String]) -> Void] = [:]
     private var capturePlanObservers: [UUID: (ForgeCapturePlan) -> Void] = [:]
     private var latestCapturePlan: ForgeCapturePlan?
+    private var logObservers: [UUID: (ForgeRenderedLog) -> Void] = [:]
 
     public init(config: ForgeAppleConfig, services: ForgeAppleServices) {
         let safeConfig = config.withPluginVersion(NPAWForge.defaultPluginVersion)
@@ -150,6 +157,11 @@ public final class ForgeApple {
         _ = runtime.setCapturePlanListener { [weak self] plan in
             self?.dispatchCapturePlan(plan)
         }
+        // Registered before start() so the kernel's own start-up decisions are
+        // the first thing a `logLevel: trace` host sees.
+        _ = runtime.setLogListener { [weak self] log in
+            self?.dispatchRenderedLog(log)
+        }
         _ = runtime.start()
         if safeConfig.startSessionOnInitialize {
             _ = startSession()
@@ -372,6 +384,20 @@ public final class ForgeApple {
         return runtime.setLogLevel(level)
     }
 
+    /// Forwards the observed device connection class to the kernel, which
+    /// applies it only when the integrator supplied no `connectionType` of
+    /// their own.
+    @discardableResult
+    public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome {
+        runtime.setAutoConnectionType(connectionType)
+    }
+
+    /// Forwards a location fix to the kernel, which owns every threshold.
+    @discardableResult
+    public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome {
+        runtime.recordLocationFix(fix)
+    }
+
     public func effectiveLogLevel() -> ForgeLogLevel {
         logger.effectiveLevel()
     }
@@ -483,6 +509,44 @@ public final class ForgeApple {
         return latest ?? runtime.capturePlan()
     }
 
+    /// Observes the kernel's rendered decision log. Console output happens
+    /// regardless of whether anything is registered here; listeners are for
+    /// hosts that want to forward the stream (the React Native binding does).
+    public func addLogListener(_ listener: @escaping (ForgeRenderedLog) -> Void) -> ForgeEventSubscription {
+        let id = UUID()
+        lock.lock()
+        logObservers[id] = listener
+        lock.unlock()
+        return ForgeEventSubscription { [weak self] in
+            self?.lock.lock()
+            self?.logObservers.removeValue(forKey: id)
+            self?.lock.unlock()
+        }
+    }
+
+    /// Sends the kernel line to the platform console through the logger, then
+    /// to every registered observer. The logger owns formatting, so observers
+    /// and the console always agree on what a line says.
+    private func dispatchRenderedLog(_ log: ForgeRenderedLog) {
+        lock.lock()
+        guard !destroyed else {
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+        guard let emitted = logger.emitRendered(
+            tag: log.tag,
+            levelName: log.level.wireName,
+            message: log.message
+        ) else {
+            return
+        }
+        lock.lock()
+        let observers = Array(logObservers.values)
+        lock.unlock()
+        observers.forEach { $0(emitted) }
+    }
+
     private func dispatchCapturePlan(_ plan: ForgeCapturePlan) {
         lock.lock()
         guard !destroyed else {
@@ -515,9 +579,11 @@ public final class ForgeApple {
         eventObservers.removeAll()
         onSendRequestListeners.removeAll()
         capturePlanObservers.removeAll()
+        logObservers.removeAll()
         recordedEvents.removeAll()
         _ = runtime.registerSessionPreSendHook(nil)
         _ = runtime.setCapturePlanListener(nil)
+        _ = runtime.setLogListener(nil)
         return runtime.destroy()
     }
 

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

@@ -207,6 +207,10 @@ public struct ForgeCapturePlan: Equatable {
         // positions stay unassigned so existing bits never renumber.
         public static let sections: UInt32 = 1 << 13
         public static let attribution: UInt32 = 1 << 14
+        /// The operator enabled at least one `mo.*` switch, so the host may
+        /// observe location. Without this bit Forge reads no location at all,
+        /// not even the authorization status.
+        public static let location: UInt32 = 1 << 15
     }
 }
 

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

@@ -38,9 +38,21 @@ public enum ForgeLogLevel: Int {
         if let level = value as? ForgeLogLevel {
             return level
         }
-        guard let raw = value.map({ String(describing: $0).lowercased() }) else {
+        guard let raw = value.map({ String(describing: $0) }) else {
             return defaultLevel
         }
+        return parse(raw) ?? defaultLevel
+    }
+
+    /// Strict counterpart to `from(_:default:)`: an unknown or blank name
+    /// yields `nil` instead of a default. Kernel-rendered lines carry their
+    /// level as a wire string, and a level Forge does not recognize must be
+    /// dropped rather than silently relabelled.
+    public static func parse(_ value: String?) -> ForgeLogLevel? {
+        guard let raw = value?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+              !raw.isEmpty else {
+            return nil
+        }
         switch raw {
         case "off": return .off
         case "error": return .error
@@ -48,11 +60,26 @@ public enum ForgeLogLevel: Int {
         case "info": return .info
         case "debug": return .debug
         case "trace": return .trace
-        default: return defaultLevel
+        default: return nil
         }
     }
 }
 
+/// A log line the kernel already rendered, level-gated and redacted. Mirrors
+/// the Android binding's `ForgeRenderedLog` so both platforms hand hosts the
+/// same shape.
+public struct ForgeRenderedLog: Equatable {
+    public let level: ForgeLogLevel
+    public let tag: String
+    public let message: String
+
+    public init(level: ForgeLogLevel, tag: String, message: String) {
+        self.level = level
+        self.tag = tag
+        self.message = message
+    }
+}
+
 public enum ForgeLogFamily: String {
     case video = "Video"
     case ad = "Ad"
@@ -68,15 +95,40 @@ public enum ForgeLogFamily: String {
 
 public protocol ForgeLogSink: AnyObject {
     func log(level: ForgeLogLevel, family: ForgeLogFamily, message: String, attributes: [String: String])
+    /// Emits a line the kernel already rendered. The kernel owns the family
+    /// label, the attribute rendering and the level gate for this stream, so
+    /// the sink receives finished text under the kernel's own tag.
+    func log(level: ForgeLogLevel, tag: String, message: String)
+}
+
+/// Additive default so sinks written before the kernel log stream existed keep
+/// compiling and still receive it, through the entry point they already
+/// implement.
+public extension ForgeLogSink {
+    func log(level: ForgeLogLevel, tag: String, message: String) {
+        log(level: level, family: .diagnostics, message: message, attributes: ["tag": tag])
+    }
 }
 
 public final class OSLogForgeLogSink: ForgeLogSink {
+    /// Prefix on every Forge Apple line, facade and kernel alike, so one grep
+    /// token finds the whole stream.
+    public static let platformTag = "NPAW-Forge-Apple"
+
     public init() {}
 
     public func log(level: ForgeLogLevel, family: ForgeLogFamily, message: String, attributes: [String: String]) {
         let rendered = "[\(family.rawValue)] \(message) \(attributes)"
         guard level != .off else { return }
-        NSLog("[NPAW-Forge-Apple] %@", rendered)
+        NSLog("[\(Self.platformTag)] %@", rendered)
+    }
+
+    public func log(level: ForgeLogLevel, tag: String, message: String) {
+        guard level != .off else { return }
+        // The kernel's own tag is kept, except when it would simply repeat the
+        // platform prefix.
+        let scope = tag.isEmpty || tag == Self.platformTag ? "" : "[\(tag)] "
+        NSLog("[\(Self.platformTag)] %@", "\(scope)\(message)")
     }
 }
 
@@ -106,4 +158,29 @@ public final class ForgeLogger {
         guard level.rawValue >= ForgeLogLevel.error.rawValue else { return }
         sink?.log(level: .error, family: family, message: action, attributes: details)
     }
+
+    /// Emits a line the kernel rendered, and returns it so the facade can fan
+    /// it out to host listeners. Malformed input (unknown level, blank
+    /// message) is dropped and reported as `nil`.
+    ///
+    /// Deliberately not re-gated against `level`: the kernel already applied
+    /// the effective level *and* the remote `lg.lvl` floor, which exists so
+    /// support can raise verbosity remotely. Re-checking the host level here
+    /// would silently defeat that floor on Apple.
+    @discardableResult
+    public func emitRendered(tag: String?, levelName: String?, message: String?) -> ForgeRenderedLog? {
+        guard let level = ForgeLogLevel.parse(levelName), level != .off else { return nil }
+        guard let message = message?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !message.isEmpty else {
+            return nil
+        }
+        let resolvedTag = tag?.trimmingCharacters(in: .whitespacesAndNewlines)
+            .nonEmpty ?? OSLogForgeLogSink.platformTag
+        sink?.log(level: level, tag: resolvedTag, message: message)
+        return ForgeRenderedLog(level: level, tag: resolvedTag, message: message)
+    }
+}
+
+private extension String {
+    var nonEmpty: String? { isEmpty ? nil : self }
 }

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

@@ -64,6 +64,13 @@ public protocol RuntimeSessionPreSendHook: AnyObject {
 public protocol ForgeRuntime: AnyObject {
     func start() -> ForgeOutcome
     func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome
+    /// Publishes the connection class the device is currently on, or `nil` to
+    /// clear it. The kernel keeps the last value and puts it on the wire only
+    /// when the integrator supplied no `connectionType` of their own.
+    func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome
+    /// Forwards a location fix. Fixes only - the kernel owns every threshold,
+    /// so the three platforms cannot drift into different definitions of moving.
+    func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView
     func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome
     /// Records a typed identity transition (`loginSuccess`, `loginFailed`,
@@ -102,6 +109,9 @@ public protocol ForgeRuntime: AnyObject {
     func setCapturePlanListener(_ listener: ((ForgeCapturePlan) -> Void)?) -> ForgeOutcome
     /// Latest kernel-emitted capture plan, or `nil` before the first emission.
     func capturePlan() -> ForgeCapturePlan?
+    /// Registers (or clears with `nil`) the kernel rendered-log observer. Lines
+    /// the kernel rendered before registration are replayed on registration.
+    func setLogListener(_ listener: ((ForgeRenderedLog) -> Void)?) -> ForgeOutcome
 }
 
 /// Additive defaults so existing `ForgeRuntime` conformances (including the
@@ -110,9 +120,17 @@ public protocol ForgeRuntime: AnyObject {
 public extension ForgeRuntime {
     func setCapturePlanListener(_ listener: ((ForgeCapturePlan) -> Void)?) -> ForgeOutcome { .accepted }
     func capturePlan() -> ForgeCapturePlan? { nil }
+    /// Additive default: runtimes with no kernel behind them render no logs,
+    /// so registration succeeds and simply never delivers.
+    func setLogListener(_ listener: ((ForgeRenderedLog) -> Void)?) -> ForgeOutcome { .accepted }
     /// Additive default: runtimes without kernel identity support report the
     /// capability gap instead of silently accepting the transition.
     func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome { .unsupportedCapability }
+    /// Additive default: a runtime with no kernel behind it has nowhere to keep
+    /// the observed connection class, so it accepts and forgets.
+    func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome { .accepted }
+    /// Additive default: no kernel behind it means nothing to derive motion with.
+    func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome { .accepted }
 }
 
 public protocol ForgeRuntimeFactory: AnyObject {
@@ -128,6 +146,8 @@ public final class UnavailableForgeRuntime: ForgeRuntime {
 
     public func start() -> ForgeOutcome { failed() }
     public func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome { .accepted }
+    public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome { .accepted }
+    public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome { .accepted }
     public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView { RuntimeVideoView(id: -1) }
     public func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome { failed() }
     public func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome { failed() }
@@ -189,12 +209,26 @@ public final class RecordingForgeRuntime: ForgeRuntime {
     public private(set) var destroyedViewIds: [Int64] = []
     public private(set) var capturePlanListener: ((ForgeCapturePlan) -> Void)?
     public private(set) var latestCapturePlan: ForgeCapturePlan?
+    public private(set) var logListener: ((ForgeRenderedLog) -> Void)?
+    /// Every connection class the observer published, in order, including the
+    /// `nil` that clears it on teardown.
+    public private(set) var publishedConnectionTypes: [String?] = []
+    /// Every location fix forwarded, in order.
+    public private(set) var recordedLocationFixes: [ForgeLocationFix] = []
     private var nextViewId: Int64 = 1
 
     public init() {}
 
     public func start() -> ForgeOutcome { .accepted }
     public func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome { .accepted }
+    public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome {
+        publishedConnectionTypes.append(connectionType)
+        return .accepted
+    }
+    public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome {
+        recordedLocationFixes.append(fix)
+        return .accepted
+    }
     public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
         createdVideoTimestamps.append(timestampMs)
         defer { nextViewId += 1 }
@@ -288,4 +322,14 @@ public final class RecordingForgeRuntime: ForgeRuntime {
         latestCapturePlan = plan
         capturePlanListener?(plan)
     }
+
+    public func setLogListener(_ listener: ((ForgeRenderedLog) -> Void)?) -> ForgeOutcome {
+        logListener = listener
+        return .accepted
+    }
+
+    /// Test hook mirroring the kernel's rendered-log push path.
+    public func emitRenderedLog(_ log: ForgeRenderedLog) {
+        logListener?(log)
+    }
 }

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

@@ -0,0 +1,183 @@
+/**
+ * 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: Apple location observation for viewer motion, reading only an authorization the host app already holds.
+ */
+import CoreLocation
+import Foundation
+
+/// A location fix forwarded to the kernel.
+///
+/// The binding forwards fixes and never verdicts: the thresholds, hysteresis
+/// and staleness rules all live in the kernel so Apple, Android and Web cannot
+/// drift into three different definitions of "moving".
+public struct ForgeLocationFix: Equatable {
+    public let latitude: Double
+    public let longitude: Double
+    /// Horizontal accuracy radius in metres. Negative means unknown, which the
+    /// kernel discards rather than guessing.
+    public let accuracyMetres: Double
+    public let timestampMs: Int64
+
+    public init(latitude: Double, longitude: Double, accuracyMetres: Double, timestampMs: Int64) {
+        self.latitude = latitude
+        self.longitude = longitude
+        self.accuracyMetres = accuracyMetres
+        self.timestampMs = timestampMs
+    }
+}
+
+/// Observes location while the host app already holds an authorization.
+///
+/// **Forge never requests location authorization.** It reads
+/// `CLLocationManager.authorizationStatus` and acts only on a grant the app
+/// obtained for its own reasons. `requestWhenInUseAuthorization` and
+/// `requestAlwaysAuthorization` appear nowhere in Forge, which is what keeps a
+/// customer's permission dialogs and App Store disclosure unchanged by
+/// integrating the SDK.
+public final class ForgeLocationObserver: NSObject {
+    private let manager: CLLocationManager
+    private let publish: (ForgeLocationFix) -> Void
+    private let lock = NSLock()
+    private var started = false
+
+    public init(
+        manager: CLLocationManager = CLLocationManager(),
+        publish: @escaping (ForgeLocationFix) -> Void
+    ) {
+        self.manager = manager
+        self.publish = publish
+        super.init()
+    }
+
+    /// Whether the host app already holds a usable authorization.
+    ///
+    /// Both `authorizedWhenInUse` and `authorizedAlways` qualify. Reduced
+    /// accuracy is deliberately accepted: the kernel's accuracy gate is what
+    /// prevents a coarse fix inventing movement, so refusing coarse grants
+    /// would lose real coverage for no privacy gain.
+    public var isAuthorized: Bool {
+        // The instance property is iOS 14 / macOS 11; the package still
+        // supports iOS 13, so the deprecated class accessor is the fallback.
+        // Both only READ the status - neither prompts.
+        let status: CLAuthorizationStatus
+        if #available(iOS 14.0, tvOS 14.0, macOS 11.0, watchOS 7.0, *) {
+            status = manager.authorizationStatus
+        } else {
+            status = CLLocationManager.authorizationStatus()
+        }
+        switch status {
+        case .authorizedAlways, .authorizedWhenInUse:
+            return true
+        case .notDetermined, .restricted, .denied:
+            return false
+        @unknown default:
+            // A status Forge does not recognise is treated as "no grant".
+            return false
+        }
+    }
+
+    /// Starts observing if an authorization is already held. Starting twice is
+    /// a no-op, so a facade that rebuilds does not stack delegates.
+    ///
+    /// Inert on tvOS. Apple does not allow continuous location updates there —
+    /// `startUpdatingLocation()` is unavailable and only the one-shot
+    /// `requestLocation()` exists — and a set-top box does not move anyway, so
+    /// deriving viewer motion on it would answer a question nobody asked. The
+    /// dimension reports `unknown` on tvOS, which is the honest value.
+    public func start() {
+        #if os(tvOS)
+        return
+        #else
+        lock.lock()
+        if started {
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+
+        guard isAuthorized else {
+            // No grant: stay completely inert. Not an error - the common case
+            // is an app that never asked for location. `started` deliberately
+            // stays false so a later grant, with the plan re-firing, can still
+            // start the observer; marking it started here would wedge the
+            // feature off for the rest of the session.
+            return
+        }
+
+        lock.lock()
+        started = true
+        lock.unlock()
+        manager.delegate = self
+        // Coarse cadence by design: this feature answers "moving or not",
+        // which needs neither navigation-grade accuracy nor its battery cost.
+        manager.desiredAccuracy = kCLLocationAccuracyHundredMeters
+        manager.distanceFilter = 50
+        #if os(iOS) || os(watchOS)
+        manager.pausesLocationUpdatesAutomatically = true
+        #endif
+        manager.startUpdatingLocation()
+        #endif
+    }
+
+    /// Stops observing. Safe to call when never started.
+    public func stop() {
+        lock.lock()
+        let wasStarted = started
+        started = false
+        lock.unlock()
+
+        guard wasStarted else { return }
+        #if !os(tvOS)
+        manager.stopUpdatingLocation()
+        #endif
+        manager.delegate = nil
+    }
+
+    /// Converts and forwards a fix. Separate from the delegate callback
+    /// because a `CLLocation` is constructible in a test while a delegate
+    /// invocation from CoreLocation is not.
+    func report(_ location: CLLocation) {
+        guard location.horizontalAccuracy >= 0 else {
+            // CoreLocation reports a negative radius when the fix is invalid.
+            return
+        }
+        publish(
+            ForgeLocationFix(
+                latitude: location.coordinate.latitude,
+                longitude: location.coordinate.longitude,
+                accuracyMetres: location.horizontalAccuracy,
+                timestampMs: Int64(location.timestamp.timeIntervalSince1970 * 1000)
+            )
+        )
+    }
+}
+
+extension ForgeLocationObserver: CLLocationManagerDelegate {
+    public func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+        guard let latest = locations.last else { return }
+        report(latest)
+    }
+
+    public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+        // A failed fix is not evidence of anything; the kernel's staleness rule
+        // decides what happens if they keep failing.
+    }
+
+    public func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        // Authorization revoked mid-session: stop observing rather than let
+        // CoreLocation keep a delegate on a manager that can no longer report.
+        // The kernel decays the dimension to `unknown` on its own.
+        if !isAuthorized {
+            stop()
+        }
+    }
+}