@mentra/bluetooth-sdk 3.1.0-dev.98 → 3.1.1-beta.230

package/ios/Source/internal/BluetoothSdkAnalyticsQueue.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+enum SendOutcome {
+    case delivered
+    case retry
+    case discard
+
+    /// 2xx is delivered. A 4xx other than 408/429 means PostHog rejected this payload
+    /// for good (bad key, malformed body) and retrying it would only block the queue.
+    /// Everything else (5xx, 408, 429) is worth retrying later.
+    static func fromHTTPStatus(_ code: Int) -> SendOutcome {
+        switch code {
+        case 200 ..< 300: return .delivered
+        case 408, 429: return .retry
+        case 400 ..< 500: return .discard
+        default: return .retry
+        }
+    }
+}
+
+/// Bounded on-disk retry queue for analytics payloads whose upload failed.
+/// One JSON object per line. Oldest entries are dropped past `maxEntries`; entries
+/// older than `maxAge` are discarded on drain. Every payload carries its own
+/// `uuid` and `timestamp`, so a retried event neither double counts nor moves in time.
+///
+/// Not thread-safe by itself: callers serialize access on the analytics transport queue.
+final class BluetoothSdkAnalyticsQueue {
+    static let defaultMaxEntries = 100
+    static let defaultMaxAge: TimeInterval = 7 * 24 * 60 * 60
+    static let fileName = "mentra_bluetooth_sdk_analytics_queue.jsonl"
+
+    static func defaultFileURL(fileManager: FileManager = .default) -> URL? {
+        guard let base = fileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else { return nil }
+        return base.appendingPathComponent("MentraBluetoothSdk", isDirectory: true).appendingPathComponent(fileName)
+    }
+
+    private let fileURL: URL
+    private let maxEntries: Int
+    private let maxAge: TimeInterval
+
+    init(fileURL: URL, maxEntries: Int = BluetoothSdkAnalyticsQueue.defaultMaxEntries, maxAge: TimeInterval = BluetoothSdkAnalyticsQueue.defaultMaxAge) {
+        self.fileURL = fileURL
+        self.maxEntries = maxEntries
+        self.maxAge = maxAge
+    }
+
+    func enqueue(_ payload: [String: Any], now: Date) {
+        var entries = read()
+        entries.append(["enqueued_at": now.timeIntervalSince1970, "payload": payload])
+        while entries.count > maxEntries {
+            entries.removeFirst()
+        }
+        write(entries)
+    }
+
+    var count: Int {
+        read().count
+    }
+
+    /// Sends queued payloads oldest-first through `send`. Delivered and permanently
+    /// rejected entries are dropped; the first retryable failure stops the drain so
+    /// ordering is preserved and a dead network does not burn through every entry.
+    func drain(now: Date, send: ([String: Any]) -> SendOutcome) {
+        let entries = read()
+        guard !entries.isEmpty else { return }
+        var remaining: [[String: Any]] = []
+        var blocked = false
+        for entry in entries {
+            let enqueuedAt = (entry["enqueued_at"] as? TimeInterval) ?? now.timeIntervalSince1970
+            if now.timeIntervalSince1970 - enqueuedAt > maxAge { continue }
+            guard let payload = entry["payload"] as? [String: Any] else { continue }
+            if blocked {
+                remaining.append(entry)
+                continue
+            }
+            if send(payload) == .retry {
+                blocked = true
+                remaining.append(entry)
+            }
+        }
+        write(remaining)
+    }
+
+    private func read() -> [[String: Any]] {
+        guard let data = try? Data(contentsOf: fileURL), let text = String(data: data, encoding: .utf8) else { return [] }
+        return text.split(separator: "\n").compactMap { line in
+            guard !line.trimmingCharacters(in: .whitespaces).isEmpty,
+                  let lineData = line.data(using: .utf8),
+                  let object = try? JSONSerialization.jsonObject(with: lineData) as? [String: Any]
+            else { return nil }
+            return object
+        }
+    }
+
+    private func write(_ entries: [[String: Any]]) {
+        let fileManager = FileManager.default
+        if entries.isEmpty {
+            try? fileManager.removeItem(at: fileURL)
+            return
+        }
+        do {
+            try fileManager.createDirectory(at: fileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+            var lines: [String] = []
+            for entry in entries {
+                guard JSONSerialization.isValidJSONObject(entry),
+                      let data = try? JSONSerialization.data(withJSONObject: entry),
+                      let line = String(data: data, encoding: .utf8)
+                else { continue }
+                lines.append(line)
+            }
+            let text = lines.joined(separator: "\n") + "\n"
+            try text.data(using: .utf8)?.write(to: fileURL, options: .atomic)
+        } catch {
+            // A queue write failure only loses retries, never live behavior.
+        }
+    }
+}

package/ios/Source/internal/BluetoothSdkAnalyticsTracker.swift

@@ -0,0 +1,157 @@
+import Foundation
+
+/// The subset of glasses status the analytics decision logic needs.
+struct AnalyticsGlassesSnapshot {
+    var connected: Bool
+    var fullyBooted: Bool
+    var model: String
+    var serialNumber: String
+    var firmwareVersion = ""
+    var besFirmwareVersion = ""
+    var mtkFirmwareVersion = ""
+    var androidVersion = ""
+    var appVersion = ""
+    var buildNumber = ""
+}
+
+struct AnalyticsEvent {
+    let name: String
+    let properties: [String: Any]
+}
+
+/// Pure decision logic for the SDK usage events. It owns no threads and no I/O so
+/// the connection/identification/heartbeat rules can be unit-tested directly.
+///
+/// Rules:
+/// - `bluetooth_sdk_glasses_connected` once per connection. If the model is not
+///   known yet at connect time the event waits for it, and is emitted without a
+///   model only if the connection ends first.
+/// - `bluetooth_sdk_glasses_identified` once per connection per serial, plus a
+///   `glasses_heartbeat` re-emission on the first status update of each new
+///   reporting day while still connected, so a connection spanning a week boundary
+///   is visible in both weeks. Reporting days follow `America/Los_Angeles`, the
+///   calendar the WAU weeks are cut on; a UTC day would miss the Sunday-evening to
+///   Monday-morning Pacific boundary, which is one UTC day.
+struct BluetoothSdkAnalyticsTracker {
+    static let millisPerDay: Int64 = 86_400_000
+    static let reportingZone = TimeZone(identifier: "America/Los_Angeles")!
+
+    /// Calendar day in the reporting zone, as days since the epoch of that zone's midnight.
+    static func reportingDay(epochMillis: Int64) -> Int64 {
+        let offsetMillis = Int64(reportingZone.secondsFromGMT(for: Date(timeIntervalSince1970: Double(epochMillis) / 1000))) * 1000
+        let local = epochMillis + offsetMillis
+        let day = local / millisPerDay
+        return local < 0 && local % millisPerDay != 0 ? day - 1 : day
+    }
+
+    static func reportingDay(date: Date = Date()) -> Int64 {
+        reportingDay(epochMillis: Int64((date.timeIntervalSince1970 * 1000).rounded(.down)))
+    }
+
+    private let simulatedModel: String
+    private var lastConnected = false
+    private var connectedPendingModel = false
+    private var identifiedSerial: String?
+    private var identifiedReportingDay: Int64?
+
+    init(simulatedModel: String) {
+        self.simulatedModel = simulatedModel
+    }
+
+    mutating func initialize(_ snapshot: AnalyticsGlassesSnapshot, reportingDay: Int64) {
+        lastConnected = snapshot.connected
+        connectedPendingModel = false
+        // Only treat identification as already captured when a valid serial is present
+        // at init. If the glasses are connected but the serial has not arrived yet
+        // (Mentra Live fills it via version_info after connect), leave this nil so the
+        // identify event still fires once the serial arrives.
+        identifiedSerial = snapshot.connected ? snapshot.serialNumber.validManufacturingSerial : nil
+        identifiedReportingDay = identifiedSerial == nil ? nil : reportingDay
+    }
+
+    mutating func observe(_ snapshot: AnalyticsGlassesSnapshot, reportingDay: Int64) -> [AnalyticsEvent] {
+        var events: [AnalyticsEvent] = []
+        let wasConnected = lastConnected
+        lastConnected = snapshot.connected
+
+        guard snapshot.connected else {
+            if connectedPendingModel {
+                connectedPendingModel = false
+                events.append(connectedEvent(snapshot, modelUnresolved: true))
+            }
+            identifiedSerial = nil
+            identifiedReportingDay = nil
+            return events
+        }
+
+        if !wasConnected {
+            identifiedSerial = nil
+            identifiedReportingDay = nil
+            if snapshot.model.isBlank {
+                connectedPendingModel = true
+            } else {
+                events.append(connectedEvent(snapshot, modelUnresolved: false))
+            }
+        } else if connectedPendingModel, !snapshot.model.isBlank {
+            connectedPendingModel = false
+            events.append(connectedEvent(snapshot, modelUnresolved: false))
+        }
+
+        guard let serial = snapshot.serialNumber.validManufacturingSerial else { return events }
+        if identifiedSerial != serial {
+            identifiedSerial = serial
+            identifiedReportingDay = reportingDay
+            events.append(identifiedEvent(snapshot, serial: serial, kind: "glasses_identified"))
+        } else if identifiedReportingDay != reportingDay {
+            identifiedReportingDay = reportingDay
+            events.append(identifiedEvent(snapshot, serial: serial, kind: "glasses_heartbeat"))
+        }
+        return events
+    }
+
+    private func connectedEvent(_ snapshot: AnalyticsGlassesSnapshot, modelUnresolved: Bool) -> AnalyticsEvent {
+        var properties: [String: Any] = [
+            "event_kind": "glasses_connected",
+            "fully_booted": snapshot.fullyBooted,
+            "glasses_is_simulated": snapshot.model == simulatedModel,
+        ]
+        if !snapshot.model.isBlank { properties["glasses_model"] = snapshot.model }
+        if modelUnresolved { properties["glasses_model_unresolved"] = true }
+        return AnalyticsEvent(name: "bluetooth_sdk_glasses_connected", properties: properties)
+    }
+
+    private func identifiedEvent(_ snapshot: AnalyticsGlassesSnapshot, serial: String, kind: String) -> AnalyticsEvent {
+        var properties: [String: Any] = [
+            "event_kind": kind,
+            "fully_booted": snapshot.fullyBooted,
+            "glasses_device_id": serial,
+            "glasses_device_id_type": "manufacturing_serial",
+            "glasses_is_simulated": snapshot.model == simulatedModel,
+        ]
+        if !snapshot.model.isBlank { properties["glasses_model"] = snapshot.model }
+        let software: [(String, String)] = [
+            ("glasses_firmware_version", snapshot.firmwareVersion),
+            ("glasses_bes_firmware_version", snapshot.besFirmwareVersion),
+            ("glasses_mtk_firmware_version", snapshot.mtkFirmwareVersion),
+            ("glasses_android_version", snapshot.androidVersion),
+            ("glasses_app_version", snapshot.appVersion),
+            ("glasses_build_number", snapshot.buildNumber),
+        ]
+        for (key, value) in software where !value.isBlank {
+            properties[key] = value
+        }
+        return AnalyticsEvent(name: "bluetooth_sdk_glasses_identified", properties: properties)
+    }
+}
+
+extension String {
+    var isBlank: Bool {
+        trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    }
+
+    var validManufacturingSerial: String? {
+        let normalized = trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalized.isEmpty, normalized.contains(where: { $0 != "0" }) else { return nil }
+        return normalized
+    }
+}

package/ios/Source/internal/BluetoothSdkAnalyticsTransport.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+/// Process-wide owner of analytics delivery: one serial queue and one retry file
+/// for the whole process. Connection tracking stays per SDK instance, but two
+/// instances can overlap briefly when the SDK is recreated, and if each owned its
+/// own queue a drain started by the old instance could rewrite the retry file over
+/// an event the new instance had just persisted. A single serial queue serializes
+/// every read-modify-write of that file.
+enum BluetoothSdkAnalyticsTransport {
+    static let queue = DispatchQueue(label: "com.mentra.bluetoothsdk.analytics.transport")
+    static let retryQueue: BluetoothSdkAnalyticsQueue? =
+        BluetoothSdkAnalyticsQueue.defaultFileURL().map { BluetoothSdkAnalyticsQueue(fileURL: $0) }
+}