@mentra/bluetooth-sdk 3.3.0-dev.822 → 3.3.0-dev.826

package/ios/Source/internal/BluetoothSdkAnalytics.swift

@@ -42,8 +42,15 @@ final class BluetoothSdkAnalytics {
     // Delivery is process-wide (see BluetoothSdkAnalyticsTransport); this instance only tracks its connection.
     private let transportQueue = BluetoothSdkAnalyticsTransport.queue
     private let configuration: BluetoothSdkAnalyticsConfiguration
+    // Tracker state is touched from the MainActor facade and store listeners;
+    // stateQueue serializes every read and write of it.
     private var tracker = BluetoothSdkAnalyticsTracker(simulatedModel: DeviceTypes.SIMULATED)
+    private var usage = BluetoothSdkUsageTracker()
     private var startedCaptured = false
+    private var lastGlasses: AnalyticsGlassesSnapshot?
+    /// Set by an SDK disconnect/forget/cancel call and consumed by the next
+    /// connected -> disconnected transition, so that transition can say why.
+    private var pendingDisconnectReason: String?
     // Touched only on transportQueue, which serializes access.
     private var resolvedHostProperties: [String: Any]?
     private var retryQueue: BluetoothSdkAnalyticsQueue? {
@@ -60,9 +67,16 @@ final class BluetoothSdkAnalytics {
         self.configuration = configuration.resolvedForApp()
     }
 
+    /// False when the host disabled analytics; callers skip building usage facts entirely.
+    var isEnabled: Bool {
+        configuration.isReady
+    }
+
     func initializeGlassesStatus(_ status: GlassesStatus) {
         stateQueue.sync {
-            tracker.initialize(status.analyticsSnapshot, reportingDay: BluetoothSdkAnalyticsTracker.reportingDay())
+            let snapshot = status.analyticsSnapshot
+            lastGlasses = snapshot
+            tracker.initialize(snapshot, reportingDay: BluetoothSdkAnalyticsTracker.reportingDay())
         }
     }
 
@@ -76,9 +90,24 @@ final class BluetoothSdkAnalytics {
         }
     }
 
-    func observeGlassesStatus(_ status: GlassesStatus) {
+    func observeGlassesStatus(_ status: GlassesStatus, phoneBluetoothOff: () -> Bool) {
         stateQueue.sync {
-            let events = tracker.observe(status.analyticsSnapshot, reportingDay: BluetoothSdkAnalyticsTracker.reportingDay())
+            let snapshot = status.analyticsSnapshot
+            lastGlasses = snapshot
+            let now = Date()
+            let events = tracker.observe(
+                snapshot,
+                reportingDay: BluetoothSdkAnalyticsTracker.reportingDay(date: now),
+                nowMs: Self.epochMillis(now)
+            ) {
+                pendingDisconnectReason
+                    ?? (phoneBluetoothOff()
+                        ? BluetoothSdkAnalyticsTracker.disconnectBluetoothOff
+                        : BluetoothSdkAnalyticsTracker.disconnectLinkLost)
+            }
+            if !snapshot.connected || events.contains(where: { $0.name == "bluetooth_sdk_glasses_connected" }) {
+                pendingDisconnectReason = nil
+            }
             guard configuration.isReady else { return }
             for event in events {
                 capture(event: event.name, properties: event.properties, configuration: configuration)
@@ -86,6 +115,45 @@ final class BluetoothSdkAnalytics {
         }
     }
 
+    func noteDisconnectRequested(_ reason: String) {
+        stateQueue.sync {
+            if lastGlasses?.connected == true { pendingDisconnectReason = reason }
+        }
+    }
+
+    func recordUsage(_ build: (inout BluetoothSdkUsageTracker) -> AnalyticsEvent?) {
+        stateQueue.sync {
+            guard configuration.isReady, let event = build(&usage) else { return }
+            capture(
+                event: event.name,
+                properties: glassesContext().merging(event.properties) { _, new in new },
+                configuration: configuration
+            )
+        }
+    }
+
+    /// Usage-tracker state changes that emit nothing themselves (e.g. a stop request).
+    func updateUsage(_ update: (inout BluetoothSdkUsageTracker) -> Void) {
+        stateQueue.sync {
+            guard configuration.isReady else { return }
+            update(&usage)
+        }
+    }
+
+    static func epochMillis(_ date: Date = Date()) -> Int64 {
+        Int64((date.timeIntervalSince1970 * 1000).rounded(.down))
+    }
+
+    /// Only ever called on `stateQueue`.
+    private func glassesContext() -> [String: Any] {
+        guard let glasses = lastGlasses, glasses.connected else { return [:] }
+        var context: [String: Any] = [:]
+        if !glasses.model.isBlank { context["glasses_model"] = glasses.model }
+        if let serial = glasses.serialNumber.validManufacturingSerial { context["glasses_device_id"] = serial }
+        if !glasses.buildNumber.isBlank { context["glasses_build_number"] = glasses.buildNumber }
+        return context
+    }
+
     private func capture(
         event: String,
         properties: [String: Any],
@@ -105,7 +173,7 @@ final class BluetoothSdkAnalytics {
                 "api_key": Self.defaultPostHogApiKey,
                 "uuid": uuid,
                 "event": event,
-                "distinct_id": self.distinctId(),
+                "distinct_id": BluetoothSdkInstallId.get(),
                 "timestamp": self.isoFormatter.string(from: capturedAt),
                 "properties": self.baseProperties(configuration: activeConfiguration)
                     .merging(host) { _, new in new }
@@ -173,7 +241,11 @@ final class BluetoothSdkAnalytics {
             "app_bundle_identifier": Bundle.main.bundleIdentifier ?? "",
             "os_platform": platform,
             "os_version": ProcessInfo.processInfo.operatingSystemVersionString,
+            "phone_manufacturer": "Apple",
+            "locale": Locale.current.identifier.replacingOccurrences(of: "_", with: "-"),
+            "timezone": TimeZone.current.identifier,
         ]
+        if let phoneModel = Self.phoneModel { properties["phone_model"] = phoneModel }
         // Always present so version cohorts never collapse into a null bucket. The
         // placeholder shows up only for unstamped source builds (plain SwiftPM checkout).
         properties["sdk_version"] = BluetoothSdkDefaults.sdkVersion ?? "unknown"
@@ -188,15 +260,15 @@ final class BluetoothSdkAnalytics {
         return resolved
     }
 
-    private func distinctId() -> String {
-        let key = "mentra_bluetooth_sdk_analytics_distinct_id"
-        if let existing = UserDefaults.standard.string(forKey: key), !existing.isEmpty {
-            return existing
+    /// The hardware identifier (e.g. `iPhone15,2`), not the user-assigned device name.
+    private static let phoneModel: String? = {
+        var systemInfo = utsname()
+        uname(&systemInfo)
+        let machine = withUnsafeBytes(of: &systemInfo.machine) { buffer in
+            String(decoding: buffer.prefix { $0 != 0 }, as: UTF8.self)
         }
-        let generated = "mentra-bt-sdk-\(UUID().uuidString)"
-        UserDefaults.standard.set(generated, forKey: key)
-        return generated
-    }
+        return machine.isEmpty ? nil : machine
+    }()
 
     private func captureURL() -> URL? {
         let normalized = Self.defaultPostHogHost.trimmingCharacters(in: .whitespacesAndNewlines).trimmingCharacters(in: CharacterSet(charactersIn: "/"))
@@ -242,7 +314,9 @@ private extension GlassesStatus {
             mtkFirmwareVersion: mtkFirmwareVersion,
             androidVersion: androidVersion,
             appVersion: appVersion,
-            buildNumber: buildNumber
+            buildNumber: buildNumber,
+            batteryLevel: batteryLevel,
+            charging: charging
         )
     }
 }

package/ios/Source/internal/BluetoothSdkAnalyticsTracker.swift

@@ -12,6 +12,9 @@ struct AnalyticsGlassesSnapshot {
     var androidVersion = ""
     var appVersion = ""
     var buildNumber = ""
+    /// -1 while the glasses have not reported a level.
+    var batteryLevel = -1
+    var charging = false
 }
 
 struct AnalyticsEvent {
@@ -32,7 +35,17 @@ struct AnalyticsEvent {
 ///   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.
+/// - `bluetooth_sdk_glasses_disconnected` when a counted connection ends, with its
+///   length, why it ended, and the battery levels seen during it. The reason is
+///   supplied by the caller: an SDK disconnect/forget/cancel call, the phone's
+///   Bluetooth turning off, or otherwise a lost link.
 struct BluetoothSdkAnalyticsTracker {
+    static let disconnectUser = "user_disconnect"
+    static let disconnectForget = "forget"
+    static let disconnectCancel = "cancel"
+    static let disconnectBluetoothOff = "bluetooth_off"
+    static let disconnectLinkLost = "link_lost"
+    static let disconnectUnknown = "unknown"
     static let millisPerDay: Int64 = 86_400_000
     static let reportingZone = TimeZone(identifier: "America/Los_Angeles")!
 
@@ -53,6 +66,11 @@ struct BluetoothSdkAnalyticsTracker {
     private var connectedPendingModel = false
     private var identifiedSerial: String?
     private var identifiedReportingDay: Int64?
+    private var connectedAtMs: Int64?
+    private var batteryAtConnect = -1
+    private var lastBattery = -1
+    private var lastCharging: Bool?
+    private var lastModel = ""
 
     init(simulatedModel: String) {
         self.simulatedModel = simulatedModel
@@ -69,7 +87,12 @@ struct BluetoothSdkAnalyticsTracker {
         identifiedReportingDay = identifiedSerial == nil ? nil : reportingDay
     }
 
-    mutating func observe(_ snapshot: AnalyticsGlassesSnapshot, reportingDay: Int64) -> [AnalyticsEvent] {
+    mutating func observe(
+        _ snapshot: AnalyticsGlassesSnapshot,
+        reportingDay: Int64,
+        nowMs: Int64 = 0,
+        disconnectReason: () -> String = { BluetoothSdkAnalyticsTracker.disconnectUnknown }
+    ) -> [AnalyticsEvent] {
         var events: [AnalyticsEvent] = []
         let wasConnected = lastConnected
         lastConnected = snapshot.connected
@@ -79,14 +102,30 @@ struct BluetoothSdkAnalyticsTracker {
                 connectedPendingModel = false
                 events.append(connectedEvent(snapshot, modelUnresolved: true))
             }
+            if let connectedAtMs {
+                events.append(disconnectedEvent(durationMs: nowMs - connectedAtMs, reason: disconnectReason()))
+            }
+            connectedAtMs = nil
             identifiedSerial = nil
             identifiedReportingDay = nil
             return events
         }
 
+        if !snapshot.model.isBlank { lastModel = snapshot.model }
+        if snapshot.batteryLevel >= 0 {
+            if batteryAtConnect < 0 { batteryAtConnect = snapshot.batteryLevel }
+            lastBattery = snapshot.batteryLevel
+            lastCharging = snapshot.charging
+        }
+
         if !wasConnected {
             identifiedSerial = nil
             identifiedReportingDay = nil
+            connectedAtMs = nowMs
+            lastModel = snapshot.model
+            batteryAtConnect = snapshot.batteryLevel
+            lastBattery = snapshot.batteryLevel
+            lastCharging = snapshot.batteryLevel >= 0 ? snapshot.charging : nil
             if snapshot.model.isBlank {
                 connectedPendingModel = true
             } else {
@@ -120,6 +159,20 @@ struct BluetoothSdkAnalyticsTracker {
         return AnalyticsEvent(name: "bluetooth_sdk_glasses_connected", properties: properties)
     }
 
+    private func disconnectedEvent(durationMs: Int64, reason: String) -> AnalyticsEvent {
+        var properties: [String: Any] = [
+            "event_kind": "glasses_disconnected",
+            "session_duration_ms": max(durationMs, 0),
+            "disconnect_reason": reason,
+            "glasses_is_simulated": lastModel == simulatedModel,
+        ]
+        if !lastModel.isBlank { properties["glasses_model"] = lastModel }
+        if batteryAtConnect >= 0 { properties["battery_level_at_connect"] = batteryAtConnect }
+        if lastBattery >= 0 { properties["battery_level_at_disconnect"] = lastBattery }
+        if let lastCharging { properties["charging"] = lastCharging }
+        return AnalyticsEvent(name: "bluetooth_sdk_glasses_disconnected", properties: properties)
+    }
+
     private func identifiedEvent(_ snapshot: AnalyticsGlassesSnapshot, serial: String, kind: String) -> AnalyticsEvent {
         var properties: [String: Any] = [
             "event_kind": kind,

package/ios/Source/internal/BluetoothSdkInstallId.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+/// One random id per app install, shared by usage analytics (as the PostHog
+/// `distinct_id`) and the startup update check, so both describe the same install.
+/// It is created on first use whether or not analytics is enabled.
+enum BluetoothSdkInstallId {
+    /// The key analytics has always stored its distinct id under; existing installs keep their id.
+    static let defaultsKey = "mentra_bluetooth_sdk_analytics_distinct_id"
+    private static let lock = NSLock()
+
+    static func get(defaults: UserDefaults = .standard) -> String {
+        lock.lock()
+        defer { lock.unlock() }
+        if let existing = defaults.string(forKey: defaultsKey), !existing.isEmpty {
+            return existing
+        }
+        let generated = "mentra-bt-sdk-\(UUID().uuidString)"
+        defaults.set(generated, forKey: defaultsKey)
+        return generated
+    }
+}

package/ios/Source/internal/BluetoothSdkUpdateCheck.swift

@@ -0,0 +1,223 @@
+import Foundation
+
+struct BluetoothSdkUpdateCheckResult: Equatable {
+    let status: String
+    let channel: String
+    let latestVersion: String?
+    let minimumSupportedVersion: String?
+
+    static func parse(_ body: Data) -> BluetoothSdkUpdateCheckResult? {
+        guard let json = (try? JSONSerialization.jsonObject(with: body)) as? [String: Any] else { return nil }
+        return BluetoothSdkUpdateCheckResult(
+            status: json["status"] as? String ?? "",
+            channel: json["channel"] as? String ?? "",
+            latestVersion: nonBlankString(json["latestVersion"]),
+            minimumSupportedVersion: nonBlankString(json["minimumSupportedVersion"])
+        )
+    }
+
+    static func parse(_ body: String) -> BluetoothSdkUpdateCheckResult? {
+        parse(Data(body.utf8))
+    }
+
+    private static func nonBlankString(_ value: Any?) -> String? {
+        guard let value = (value as? String)?.trimmingCharacters(in: .whitespacesAndNewlines), !value.isEmpty else {
+            return nil
+        }
+        return value
+    }
+}
+
+/// The developer-facing console banner for an out-of-date SDK. Never shown in app UI.
+enum BluetoothSdkUpdateNotice {
+    static let statusUpdateAvailable = "update_available"
+    static let statusUnsupported = "unsupported"
+    private static let rule = "=================================================================="
+
+    /// Nil when the installed SDK is current or the server could not tell.
+    static func banner(installedVersion: String, result: BluetoothSdkUpdateCheckResult, surface: String) -> String? {
+        let latest = result.latestVersion
+        let heading: String
+        switch result.status {
+        case statusUnsupported:
+            heading = "MENTRA BLUETOOTH SDK \(installedVersion) IS NO LONGER SUPPORTED"
+        case statusUpdateAvailable:
+            guard latest != nil else { return nil }
+            heading = "MENTRA BLUETOOTH SDK UPDATE AVAILABLE"
+        default:
+            return nil
+        }
+        var lines = [
+            rule,
+            "  \(heading)",
+            "  Installed: \(installedVersion)    Latest: \(latest ?? "unknown")",
+            "  Update:    \(updateLine(surface: surface, version: latest))",
+        ]
+        if result.status == statusUnsupported {
+            lines.append("  This version has known issues that are fixed in newer releases.")
+        }
+        lines.append("  Running an old SDK is the most common cause of glasses issues.")
+        lines.append(rule)
+        return lines.joined(separator: "\n")
+    }
+
+    private static func updateLine(surface: String, version: String?) -> String {
+        switch surface {
+        case "react_native": return "bun add @mentra/bluetooth-sdk@\(version ?? "latest")"
+        case "ios": return "the MentraBluetoothSDK Swift package at \(version ?? "its latest release")"
+        default: return "com.mentraglass:bluetooth-sdk:\(version ?? "<latest release>")"
+        }
+    }
+}
+
+/// Checks Mentra Core for a newer SDK on every SDK start and, when this SDK is
+/// behind, prints a console banner now and every `reprintInterval` while the SDK
+/// instance lives. The check is one request with a short timeout and no retry;
+/// any failure is silent and changes no SDK behavior. It runs regardless of the
+/// analytics setting.
+final class BluetoothSdkUpdateCheck {
+    /// Posts the JSON body and completes with the 200 response body, or nil on any failure.
+    typealias Transport = @Sendable (_ body: Data, _ completion: @escaping @Sendable (Data?) -> Void) -> Void
+    typealias NoticeHandler = @Sendable (_ banner: String, _ result: BluetoothSdkUpdateCheckResult) -> Void
+
+    static let updateCheckUrl = URL(string: "https://core.mentraglass.com/api/client/bluetooth-sdk/update-check")!
+    static let reprintInterval: TimeInterval = 15 * 60
+    private static let timeout: TimeInterval = 4
+    private static let queue = DispatchQueue(label: "com.mentra.bluetoothsdk.update-check", qos: .utility)
+    private static let session: URLSession = {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = timeout
+        configuration.timeoutIntervalForResource = timeout
+        configuration.waitsForConnectivity = false
+        return URLSession(configuration: configuration)
+    }()
+
+    private let surface: String
+    private let sdkVersion: String?
+    private let bundle: Bundle
+    private let transport: Transport
+    private let onNotice: NoticeHandler
+    // Recursive so a notice handler that stops the check cannot deadlock it.
+    private let lock = NSRecursiveLock()
+    private var stopped = false
+    private var reprintTimer: DispatchSourceTimer?
+
+    init(
+        surface: String,
+        sdkVersion: String? = BluetoothSdkDefaults.sdkVersion,
+        bundle: Bundle = .main,
+        transport: @escaping Transport = { body, completion in BluetoothSdkUpdateCheck.post(body, completion: completion) },
+        onNotice: @escaping NoticeHandler
+    ) {
+        self.surface = surface
+        self.sdkVersion = sdkVersion
+        self.bundle = bundle
+        self.transport = transport
+        self.onNotice = onNotice
+    }
+
+    deinit {
+        reprintTimer?.cancel()
+    }
+
+    /// The update line follows the integration surface: React Native, or the Swift package.
+    static func surface(forAnalyticsSurface analyticsSurface: String) -> String {
+        analyticsSurface == "react_native" ? "react_native" : "ios"
+    }
+
+    static func isCheckable(_ version: String?) -> Bool {
+        guard let version else { return false }
+        let trimmed = version.trimmingCharacters(in: .whitespacesAndNewlines)
+        return !trimmed.isEmpty && trimmed != "unknown"
+    }
+
+    func start() {
+        guard Self.isCheckable(sdkVersion) else { return }
+        // Bundle and UserDefaults lookups stay off the caller (often main) thread.
+        Self.queue.async { [weak self] in
+            guard let self else { return }
+            let requestBody = self.requestBody()
+            guard JSONSerialization.isValidJSONObject(requestBody),
+                  let body = try? JSONSerialization.data(withJSONObject: requestBody)
+            else { return }
+            self.transport(body) { [weak self] response in
+                self?.handle(response)
+            }
+        }
+    }
+
+    func stop() {
+        lock.lock()
+        defer { lock.unlock() }
+        stopped = true
+        reprintTimer?.cancel()
+        reprintTimer = nil
+    }
+
+    private func handle(_ response: Data?) {
+        guard let response,
+              let sdkVersion,
+              let result = BluetoothSdkUpdateCheckResult.parse(response),
+              let banner = BluetoothSdkUpdateNotice.banner(installedVersion: sdkVersion, result: result, surface: surface)
+        else { return }
+        lock.lock()
+        defer { lock.unlock() }
+        guard !stopped, reprintTimer == nil else { return }
+        onNotice(banner, result)
+        let timer = DispatchSource.makeTimerSource(queue: Self.queue)
+        timer.schedule(deadline: .now() + Self.reprintInterval, repeating: Self.reprintInterval)
+        timer.setEventHandler { [weak self] in
+            guard let self else { return }
+            self.lock.lock()
+            defer { self.lock.unlock() }
+            if !self.stopped { self.onNotice(banner, result) }
+        }
+        reprintTimer = timer
+        timer.resume()
+    }
+
+    func requestBody() -> [String: Any] {
+        let host = BluetoothSdkAnalyticsHost.resolve(bundle: bundle)
+        #if os(macOS)
+            let osPlatform = "macos"
+        #else
+            let osPlatform = "ios"
+        #endif
+        var body: [String: Any] = [
+            "install_id": BluetoothSdkInstallId.get(),
+            "app_identifier": bundle.bundleIdentifier ?? "",
+            "app_build_type": host.buildType,
+            "app_install_source": host.installSource,
+            "sdk_version": sdkVersion ?? "unknown",
+            // Core accepts `android` or `ios`; the macOS build ships in the same Swift package.
+            "sdk_platform": "ios",
+            "sdk_surface": surface,
+            "os_platform": osPlatform,
+            "os_version": ProcessInfo.processInfo.operatingSystemVersionString,
+        ]
+        if let appVersion = host.appVersion { body["app_version"] = appVersion }
+        if let appBuild = host.appBuild { body["app_build"] = appBuild }
+        if let environment = host.environment { body["app_environment"] = environment }
+        return body
+    }
+
+    static func post(_ body: Data, completion: @escaping @Sendable (Data?) -> Void) {
+        var request = URLRequest(url: updateCheckUrl)
+        request.httpMethod = "POST"
+        request.timeoutInterval = timeout
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = body
+        session.dataTask(with: request) { data, response, error in
+            guard error == nil, (response as? HTTPURLResponse)?.statusCode == 200 else {
+                completion(nil)
+                return
+            }
+            completion(data)
+        }.resume()
+    }
+
+    /// Test hook: waits until every task submitted to the check queue so far has run.
+    static func awaitIdle() {
+        queue.sync {}
+    }
+}