@mentra/bluetooth-sdk 3.2.0-dev.209 → 3.2.0-dev.210

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsTracker.kt

@@ -0,0 +1,139 @@
+package com.mentra.bluetoothsdk
+
+import java.util.TimeZone
+
+/** The subset of glasses status the analytics decision logic needs. */
+internal data class AnalyticsGlassesSnapshot(
+    val connected: Boolean,
+    val fullyBooted: Boolean,
+    val model: String,
+    val serialNumber: String,
+    val firmwareVersion: String = "",
+    val besFirmwareVersion: String = "",
+    val mtkFirmwareVersion: String = "",
+    val androidVersion: String = "",
+    val appVersion: String = "",
+    val buildNumber: String = "",
+)
+
+internal data class AnalyticsEvent(
+    val name: String,
+    val properties: Map<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 (Mentra Live and some Android
+ *   paths set the model after the connected flag), 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.
+ */
+internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String) {
+    private var lastConnected = false
+    private var connectedPendingModel = false
+    private var identifiedSerial: String? = null
+    private var identifiedReportingDay: Long? = null
+
+    fun initialize(snapshot: AnalyticsGlassesSnapshot, reportingDay: Long) {
+        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 null so the
+        // identify event still fires once the serial arrives.
+        identifiedSerial = if (snapshot.connected) snapshot.serialNumber.validManufacturingSerial() else null
+        identifiedReportingDay = identifiedSerial?.let { reportingDay }
+    }
+
+    fun observe(snapshot: AnalyticsGlassesSnapshot, reportingDay: Long): List<AnalyticsEvent> {
+        val events = mutableListOf<AnalyticsEvent>()
+        val wasConnected = lastConnected
+        lastConnected = snapshot.connected
+
+        if (!snapshot.connected) {
+            if (connectedPendingModel) {
+                connectedPendingModel = false
+                events += connectedEvent(snapshot, modelUnresolved = true)
+            }
+            identifiedSerial = null
+            identifiedReportingDay = null
+            return events
+        }
+
+        if (!wasConnected) {
+            identifiedSerial = null
+            identifiedReportingDay = null
+            if (snapshot.model.isBlank()) {
+                connectedPendingModel = true
+            } else {
+                events += connectedEvent(snapshot, modelUnresolved = false)
+            }
+        } else if (connectedPendingModel && snapshot.model.isNotBlank()) {
+            connectedPendingModel = false
+            events += connectedEvent(snapshot, modelUnresolved = false)
+        }
+
+        val serial = snapshot.serialNumber.validManufacturingSerial() ?: return events
+        if (identifiedSerial != serial) {
+            identifiedSerial = serial
+            identifiedReportingDay = reportingDay
+            events += identifiedEvent(snapshot, serial, kind = "glasses_identified")
+        } else if (identifiedReportingDay != reportingDay) {
+            identifiedReportingDay = reportingDay
+            events += identifiedEvent(snapshot, serial, kind = "glasses_heartbeat")
+        }
+        return events
+    }
+
+    private fun connectedEvent(snapshot: AnalyticsGlassesSnapshot, modelUnresolved: Boolean) =
+        AnalyticsEvent(
+            "bluetooth_sdk_glasses_connected",
+            buildMap {
+                put("event_kind", "glasses_connected")
+                put("fully_booted", snapshot.fullyBooted)
+                snapshot.model.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+                if (modelUnresolved) put("glasses_model_unresolved", true)
+                put("glasses_is_simulated", snapshot.model == simulatedModel)
+            },
+        )
+
+    private fun identifiedEvent(snapshot: AnalyticsGlassesSnapshot, serial: String, kind: String) =
+        AnalyticsEvent(
+            "bluetooth_sdk_glasses_identified",
+            buildMap {
+                put("event_kind", kind)
+                put("fully_booted", snapshot.fullyBooted)
+                put("glasses_device_id", serial)
+                put("glasses_device_id_type", "manufacturing_serial")
+                snapshot.model.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+                put("glasses_is_simulated", snapshot.model == simulatedModel)
+                snapshot.firmwareVersion.takeIf { it.isNotBlank() }?.let { put("glasses_firmware_version", it) }
+                snapshot.besFirmwareVersion.takeIf { it.isNotBlank() }?.let { put("glasses_bes_firmware_version", it) }
+                snapshot.mtkFirmwareVersion.takeIf { it.isNotBlank() }?.let { put("glasses_mtk_firmware_version", it) }
+                snapshot.androidVersion.takeIf { it.isNotBlank() }?.let { put("glasses_android_version", it) }
+                snapshot.appVersion.takeIf { it.isNotBlank() }?.let { put("glasses_app_version", it) }
+                snapshot.buildNumber.takeIf { it.isNotBlank() }?.let { put("glasses_build_number", it) }
+            },
+        )
+
+    companion object {
+        const val MILLIS_PER_DAY = 86_400_000L
+        val REPORTING_ZONE: TimeZone = TimeZone.getTimeZone("America/Los_Angeles")
+
+        /** Calendar day in the reporting zone, as days since the epoch of that zone's midnight. */
+        fun reportingDay(epochMillis: Long): Long =
+            Math.floorDiv(epochMillis + REPORTING_ZONE.getOffset(epochMillis), MILLIS_PER_DAY)
+    }
+}
+
+internal fun String.validManufacturingSerial(): String? =
+    trim().takeIf { it.isNotEmpty() && !it.matches(Regex("0+")) }

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsTransport.kt

@@ -0,0 +1,49 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import java.io.File
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.RejectedExecutionException
+
+/**
+ * Process-wide owner of analytics delivery: one serial executor and one retry
+ * queue 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 executor a drain started by the old instance could rewrite the
+ * retry file over an event the new instance had just persisted. A single
+ * executor serializes every read-modify-write of that file.
+ */
+internal object BluetoothSdkAnalyticsTransport {
+    private val executor: ExecutorService =
+        Executors.newSingleThreadExecutor { runnable ->
+            Thread(runnable, "MentraBluetoothSdkAnalytics").apply { isDaemon = true }
+        }
+
+    @Volatile
+    private var queue: BluetoothSdkAnalyticsQueue? = null
+
+    fun queue(context: Context): BluetoothSdkAnalyticsQueue =
+        queue ?: synchronized(this) {
+            queue ?: BluetoothSdkAnalyticsQueue(File(context.applicationContext.filesDir, BluetoothSdkAnalyticsQueue.FILE_NAME))
+                .also { queue = it }
+        }
+
+    /** Runs [block] on the transport executor; analytics must never affect SDK behavior. */
+    fun submit(block: () -> Unit) {
+        try {
+            executor.execute {
+                try {
+                    block()
+                } catch (_: Exception) {
+                }
+            }
+        } catch (_: RejectedExecutionException) {
+        }
+    }
+
+    /** Test hook: waits until every task submitted so far has run. */
+    internal fun awaitIdle() {
+        executor.submit {}.get()
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedChangelogCatalog.kt

@@ -4,5 +4,5 @@ package com.mentra.bluetoothsdk
 internal val GENERATED_RELEASE_CHANGELOGS: List<ReleaseChangelog> =
     listOf(
         ReleaseChangelog(version = "3.2.0", markdown = "This release is under active development. User-facing changes will be documented as they land.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`."),
-        ReleaseChangelog(version = "3.1.0", markdown = "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
+        ReleaseChangelog(version = "3.1.0", markdown = "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them."),
     )

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.209"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.209"
-    const val SOURCE_COMMIT: String = "b1606374e1508f0993d1a7e391fddeb4f8fac5bd"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.209.json"
-    const val OTA_MANIFEST_SHA256: String = "de5936b765f7deb07a1fd448bb4e9c00f36e1b1313d16c021aff843cf801b489"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.210"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.210"
+    const val SOURCE_COMMIT: String = "259fb93fd2ecae4ed7bf280fe3b4e2b2cc594611"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.210.json"
+    const val OTA_MANIFEST_SHA256: String = "7d8fb1f69ca9a0a6b9d00f87a60694e74aa5377776d1818a7b982b09d9bb65dc"
 }

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/G2.kt

@@ -1921,9 +1921,19 @@ class G2 : SGCManager() {
 
         // Set device_name so DeviceManager can save it for reconnection
         val peripheralName = rightGatt?.device?.name ?: leftGatt?.device?.name
-        val serialNumber = peripheralName?.let { deviceNameToSerialNumber[it] }
+        val serialNumber =
+            G2SerialResolution.resolve(
+                scannedSerial = peripheralName?.let { deviceNameToSerialNumber[it] },
+                requestedId = DEVICE_SEARCH_ID,
+                persistedDeviceName = DeviceStore.get("bluetooth", "device_name") as? String ?: "",
+            )
         if (serialNumber != null) {
             DeviceStore.apply("bluetooth", "device_name", serialNumber)
+            // The advertisement serial is the manufacturing serial; expose it where
+            // the SDK status (and analytics identification) read it, not only in the
+            // reconnection name slot. Cached reconnects skip the scan, so the
+            // persisted name is the serial source there (see G2SerialResolution).
+            DeviceStore.apply("glasses", "serialNumber", serialNumber)
             Bridge.log("G2: Set device_name to $serialNumber")
         }
 

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/G2SerialResolution.kt

@@ -0,0 +1,23 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/**
+ * Which manufacturing serial to publish for a G2 connection.
+ *
+ * A fresh pairing decodes the serial from the advertisement during the scan. A
+ * cached reconnect (address based, after a process restart) skips the scan, so the
+ * only serial the SDK still holds is the one it persisted as the device name at
+ * the previous auth completion. That persisted value is reused only when it is
+ * exactly the id this connection was asked for: the search id can be a partial
+ * string typed by a host, and a partial must never be reported as a serial.
+ */
+internal object G2SerialResolution {
+    private const val UNSET = "NOT_SET"
+
+    fun resolve(
+        scannedSerial: String?,
+        requestedId: String,
+        persistedDeviceName: String,
+    ): String? =
+        scannedSerial?.trim()?.takeIf { it.isNotEmpty() }
+            ?: persistedDeviceName.trim().takeIf { it.isNotEmpty() && it != UNSET && it == requestedId.trim() }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsHostTest.kt

@@ -0,0 +1,64 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class BluetoothSdkAnalyticsHostTest {
+    @Test
+    fun `maps known store installers and treats a missing installer as sideload`() {
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("com.android.vending")).isEqualTo("play_store")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("com.amazon.venezia")).isEqualTo("amazon_appstore")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("com.sec.android.app.samsungapps")).isEqualTo("galaxy_store")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("com.example.thirdparty.store")).isEqualTo("other_store")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor(null)).isEqualTo("sideload")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("  ")).isEqualTo("sideload")
+    }
+
+    @Test
+    fun `a failed installer lookup is unknown, never a guess`() {
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor(null, lookupFailed = true)).isEqualTo("unknown")
+        assertThat(BluetoothSdkAnalyticsHost.installSourceFor("com.android.vending", lookupFailed = true)).isEqualTo("unknown")
+    }
+
+    @Test
+    fun `normalizes the host environment and rejects values that cannot be filtered on`() {
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment(" Prod ")).isEqualTo("prod")
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment("staging-eu_1")).isEqualTo("staging-eu_1")
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment(null)).isNull()
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment("")).isNull()
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment("-leading")).isNull()
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment("has space")).isNull()
+        assertThat(BluetoothSdkAnalyticsHost.normalizedEnvironment("a".repeat(33))).isNull()
+    }
+
+    @Test
+    fun `serializes only the facts that are known`() {
+        val full =
+            BluetoothSdkAnalyticsHostProperties(
+                appVersion = "3.2.0",
+                appBuild = "53356754",
+                buildType = "release",
+                installSource = "play_store",
+                installerPackage = "com.android.vending",
+                environment = "prod",
+            ).toMap()
+        assertThat(full)
+            .containsEntry("app_version", "3.2.0")
+            .containsEntry("app_build", "53356754")
+            .containsEntry("app_build_type", "release")
+            .containsEntry("app_install_source", "play_store")
+            .containsEntry("app_installer_package", "com.android.vending")
+            .containsEntry("app_environment", "prod")
+
+        val sparse =
+            BluetoothSdkAnalyticsHostProperties(
+                appVersion = null,
+                appBuild = null,
+                buildType = "debug",
+                installSource = "sideload",
+                installerPackage = null,
+                environment = null,
+            ).toMap()
+        assertThat(sparse).containsOnlyKeys("app_build_type", "app_install_source")
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsQueueTest.kt

@@ -0,0 +1,86 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.json.JSONObject
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+
+class BluetoothSdkAnalyticsQueueTest {
+    @get:Rule
+    val folder = TemporaryFolder()
+
+    private fun payload(id: String) = JSONObject().put("uuid", id).put("event", "bluetooth_sdk_started")
+
+    @Test
+    fun `drains oldest first and keeps what still fails, preserving order`() {
+        val queue = BluetoothSdkAnalyticsQueue(folder.newFile("queue.jsonl"))
+        queue.enqueue(payload("a"), nowMillis = 1_000)
+        queue.enqueue(payload("b"), nowMillis = 2_000)
+        queue.enqueue(payload("c"), nowMillis = 3_000)
+
+        val sent = mutableListOf<String>()
+        queue.drain(nowMillis = 4_000) { p ->
+            val id = p.getString("uuid")
+            if (id == "b") SendOutcome.RETRY else SendOutcome.DELIVERED.also { sent.add(id) }
+        }
+        assertThat(sent).containsExactly("a")
+        assertThat(queue.size()).isEqualTo(2)
+
+        val second = mutableListOf<String>()
+        queue.drain(nowMillis = 5_000) { SendOutcome.DELIVERED.also { _ -> second.add(it.getString("uuid")) } }
+        assertThat(second).containsExactly("b", "c")
+        assertThat(queue.size()).isZero()
+    }
+
+    @Test
+    fun `drops the oldest entries past the cap and expired entries on drain`() {
+        val queue = BluetoothSdkAnalyticsQueue(folder.newFile("queue.jsonl"), maxEntries = 2, maxAgeMillis = 10_000)
+        queue.enqueue(payload("old"), nowMillis = 0)
+        queue.enqueue(payload("mid"), nowMillis = 5_000)
+        queue.enqueue(payload("new"), nowMillis = 6_000)
+        assertThat(queue.size()).isEqualTo(2)
+
+        val sent = mutableListOf<String>()
+        queue.drain(nowMillis = 16_000) { SendOutcome.DELIVERED.also { _ -> sent.add(it.getString("uuid")) } }
+        assertThat(sent).containsExactly("new")
+    }
+
+    @Test
+    fun `survives a corrupt line and a throwing sender`() {
+        val file = folder.newFile("queue.jsonl")
+        val queue = BluetoothSdkAnalyticsQueue(file)
+        queue.enqueue(payload("a"), nowMillis = 1_000)
+        file.appendText("not json\n")
+        queue.enqueue(payload("b"), nowMillis = 2_000)
+        assertThat(queue.size()).isEqualTo(2)
+
+        queue.drain(nowMillis = 3_000) { throw IllegalStateException("network") }
+        assertThat(queue.size()).isEqualTo(2)
+    }
+
+    @Test
+    fun `a permanently rejected payload is dropped without blocking the rest`() {
+        val queue = BluetoothSdkAnalyticsQueue(folder.newFile("queue.jsonl"))
+        queue.enqueue(payload("bad"), nowMillis = 1_000)
+        queue.enqueue(payload("good"), nowMillis = 2_000)
+
+        val sent = mutableListOf<String>()
+        queue.drain(nowMillis = 3_000) { p ->
+            val id = p.getString("uuid")
+            if (id == "bad") SendOutcome.DISCARD else SendOutcome.DELIVERED.also { sent.add(id) }
+        }
+        assertThat(sent).containsExactly("good")
+        assertThat(queue.size()).isZero()
+    }
+
+    @Test
+    fun `http status maps to an outcome`() {
+        assertThat(SendOutcome.fromHttpStatus(200)).isEqualTo(SendOutcome.DELIVERED)
+        assertThat(SendOutcome.fromHttpStatus(400)).isEqualTo(SendOutcome.DISCARD)
+        assertThat(SendOutcome.fromHttpStatus(401)).isEqualTo(SendOutcome.DISCARD)
+        assertThat(SendOutcome.fromHttpStatus(408)).isEqualTo(SendOutcome.RETRY)
+        assertThat(SendOutcome.fromHttpStatus(429)).isEqualTo(SendOutcome.RETRY)
+        assertThat(SendOutcome.fromHttpStatus(503)).isEqualTo(SendOutcome.RETRY)
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsTrackerTest.kt

@@ -0,0 +1,148 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+import java.time.Instant
+
+class BluetoothSdkAnalyticsTrackerTest {
+    private val tracker = BluetoothSdkAnalyticsTracker(simulatedModel = "Simulated Glasses")
+
+    private fun snapshot(
+        connected: Boolean,
+        model: String = "Mentra Live",
+        serial: String = "",
+        fullyBooted: Boolean = connected,
+    ) = AnalyticsGlassesSnapshot(connected = connected, fullyBooted = fullyBooted, model = model, serialNumber = serial)
+
+    @Test
+    fun `connect then serial emits connected and identified once, reconnects do not repeat identification within a connection`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        val first = tracker.observe(snapshot(connected = true), reportingDay = 100)
+        assertThat(first.map { it.name }).containsExactly("bluetooth_sdk_glasses_connected")
+
+        val identified = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(identified.map { it.name }).containsExactly("bluetooth_sdk_glasses_identified")
+        assertThat(identified.single().properties)
+            .containsEntry("event_kind", "glasses_identified")
+            .containsEntry("glasses_device_id", "MLAB0001")
+            .containsEntry("glasses_is_simulated", false)
+
+        assertThat(tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)).isEmpty()
+    }
+
+    @Test
+    fun `a new connection identifies the same serial again`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        tracker.observe(snapshot(connected = false), reportingDay = 100)
+        val again = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(again.map { it.name })
+            .containsExactly("bluetooth_sdk_glasses_connected", "bluetooth_sdk_glasses_identified")
+    }
+
+    @Test
+    fun `connected waits for the model and is emitted once the model arrives`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        assertThat(tracker.observe(snapshot(connected = true, model = ""), reportingDay = 100)).isEmpty()
+        val withModel = tracker.observe(snapshot(connected = true, model = "Even Realities G2"), reportingDay = 100)
+        assertThat(withModel.single().name).isEqualTo("bluetooth_sdk_glasses_connected")
+        assertThat(withModel.single().properties).containsEntry("glasses_model", "Even Realities G2")
+        assertThat(withModel.single().properties).doesNotContainKey("glasses_model_unresolved")
+    }
+
+    @Test
+    fun `connected without a model is still counted when the connection ends first`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        tracker.observe(snapshot(connected = true, model = ""), reportingDay = 100)
+        val ended = tracker.observe(snapshot(connected = false, model = ""), reportingDay = 100)
+        assertThat(ended.single().name).isEqualTo("bluetooth_sdk_glasses_connected")
+        assertThat(ended.single().properties).containsEntry("glasses_model_unresolved", true).doesNotContainKey("glasses_model")
+    }
+
+    @Test
+    fun `a connection that crosses a UTC day boundary heartbeats once per day`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)).isEmpty()
+
+        val nextDay = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 101)
+        assertThat(nextDay.single().name).isEqualTo("bluetooth_sdk_glasses_identified")
+        assertThat(nextDay.single().properties).containsEntry("event_kind", "glasses_heartbeat")
+        assertThat(tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 101)).isEmpty()
+    }
+
+    @Test
+    fun `initializing while already connected and identified suppresses a duplicate identification but not later heartbeats`() {
+        tracker.initialize(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)).isEmpty()
+        val nextDay = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 101)
+        assertThat(nextDay.single().properties).containsEntry("event_kind", "glasses_heartbeat")
+    }
+
+    @Test
+    fun `initializing while connected but before the serial arrives still identifies later`() {
+        tracker.initialize(snapshot(connected = true, serial = ""), reportingDay = 100)
+        val identified = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = 100)
+        assertThat(identified.single().properties).containsEntry("event_kind", "glasses_identified")
+    }
+
+    @Test
+    fun `placeholder serials are ignored and simulated glasses are flagged`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        val events = tracker.observe(snapshot(connected = true, model = "Simulated Glasses", serial = "0000"), reportingDay = 100)
+        assertThat(events.map { it.name }).containsExactly("bluetooth_sdk_glasses_connected")
+        assertThat(events.single().properties).containsEntry("glasses_is_simulated", true)
+    }
+
+    @Test
+    fun `identification carries the glasses software versions that are known`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 100)
+        val events =
+            tracker.observe(
+                AnalyticsGlassesSnapshot(
+                    connected = true,
+                    fullyBooted = true,
+                    model = "Mentra Live",
+                    serialNumber = "MLAB0001",
+                    firmwareVersion = "26.9.3.0",
+                    mtkFirmwareVersion = "20260709",
+                    appVersion = "5.2.1",
+                ),
+                reportingDay = 100,
+            )
+        val identified = events.single { it.name == "bluetooth_sdk_glasses_identified" }
+        assertThat(identified.properties)
+            .containsEntry("glasses_firmware_version", "26.9.3.0")
+            .containsEntry("glasses_mtk_firmware_version", "20260709")
+            .containsEntry("glasses_app_version", "5.2.1")
+            .doesNotContainKeys("glasses_bes_firmware_version", "glasses_android_version", "glasses_build_number")
+    }
+
+    @Test
+    fun `reporting day follows the Los Angeles calendar, not UTC`() {
+        val sundayEveningPacific = Instant.parse("2026-09-14T00:30:00Z").toEpochMilli() // Sun 2026-09-13 17:30 PDT
+        val mondayEarlyPacific = Instant.parse("2026-09-14T08:00:00Z").toEpochMilli() // Mon 2026-09-14 01:00 PDT
+        assertThat(Math.floorDiv(sundayEveningPacific, 86_400_000L)).isEqualTo(Math.floorDiv(mondayEarlyPacific, 86_400_000L))
+        assertThat(BluetoothSdkAnalyticsTracker.reportingDay(sundayEveningPacific))
+            .isEqualTo(BluetoothSdkAnalyticsTracker.reportingDay(mondayEarlyPacific) - 1)
+
+        // Spring-forward day: 01:30 PST and 03:30 PDT are the same Pacific day.
+        val beforeDst = Instant.parse("2026-03-08T09:30:00Z").toEpochMilli()
+        val afterDst = Instant.parse("2026-03-08T10:30:00Z").toEpochMilli()
+        assertThat(BluetoothSdkAnalyticsTracker.reportingDay(beforeDst)).isEqualTo(BluetoothSdkAnalyticsTracker.reportingDay(afterDst))
+        // Pacific midnight is the boundary.
+        val justBeforeMidnight = Instant.parse("2026-09-14T06:59:59Z").toEpochMilli()
+        val midnight = Instant.parse("2026-09-14T07:00:00Z").toEpochMilli()
+        assertThat(BluetoothSdkAnalyticsTracker.reportingDay(justBeforeMidnight) + 1).isEqualTo(BluetoothSdkAnalyticsTracker.reportingDay(midnight))
+    }
+
+    @Test
+    fun `a connection across the Pacific Sunday to Monday boundary heartbeats on Monday`() {
+        tracker.initialize(snapshot(connected = false), reportingDay = 0)
+        val sunday = BluetoothSdkAnalyticsTracker.reportingDay(Instant.parse("2026-09-14T00:30:00Z").toEpochMilli())
+        val monday = BluetoothSdkAnalyticsTracker.reportingDay(Instant.parse("2026-09-14T08:00:00Z").toEpochMilli())
+        tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = sunday)
+        val onMonday = tracker.observe(snapshot(connected = true, serial = "MLAB0001"), reportingDay = monday)
+        assertThat(onMonday.single().properties).containsEntry("event_kind", "glasses_heartbeat")
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/BluetoothSdkAnalyticsTransportTest.kt

@@ -0,0 +1,44 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.json.JSONObject
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+class BluetoothSdkAnalyticsTransportTest {
+    @get:Rule
+    val folder = TemporaryFolder()
+
+    private fun payload(id: String) = JSONObject().put("uuid", id)
+
+    @Test
+    fun `a drain started by an old instance cannot overwrite an event a new instance persists`() {
+        val queue = BluetoothSdkAnalyticsQueue(folder.newFile("queue.jsonl"))
+        queue.enqueue(payload("old"), nowMillis = 1_000)
+        val drainStarted = CountDownLatch(1)
+        val newInstanceReady = CountDownLatch(1)
+
+        // "Old instance": a slow drain that snapshots the file, then rewrites it.
+        BluetoothSdkAnalyticsTransport.submit {
+            queue.drain(nowMillis = 2_000) {
+                drainStarted.countDown()
+                newInstanceReady.await(2, TimeUnit.SECONDS)
+                SendOutcome.DELIVERED
+            }
+        }
+        // "New instance": persists a failed event while that drain is in progress.
+        // Through the shared executor it is serialized after the drain instead of
+        // racing its rewrite.
+        assertThat(drainStarted.await(2, TimeUnit.SECONDS)).isTrue()
+        BluetoothSdkAnalyticsTransport.submit { queue.enqueue(payload("new"), nowMillis = 3_000) }
+        newInstanceReady.countDown()
+        BluetoothSdkAnalyticsTransport.awaitIdle()
+
+        val remaining = mutableListOf<String>()
+        queue.drain(nowMillis = 4_000) { p -> SendOutcome.RETRY.also { remaining.add(p.getString("uuid")) } }
+        assertThat(remaining).containsExactly("new")
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/G2SerialResolutionTest.kt

@@ -0,0 +1,25 @@
+package com.mentra.bluetoothsdk
+
+import com.mentra.bluetoothsdk.sgcs.G2SerialResolution
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class G2SerialResolutionTest {
+    @Test
+    fun `a scanned serial always wins`() {
+        assertThat(G2SerialResolution.resolve("S2ABCD12345678", "OTHER", "S2OLD000000000")).isEqualTo("S2ABCD12345678")
+    }
+
+    @Test
+    fun `a cached reconnect reuses the persisted serial only when it is the requested id`() {
+        assertThat(G2SerialResolution.resolve(null, "S2ABCD12345678", "S2ABCD12345678")).isEqualTo("S2ABCD12345678")
+        assertThat(G2SerialResolution.resolve(null, "12345678", "S2ABCD12345678")).isNull()
+        assertThat(G2SerialResolution.resolve(null, "S2ABCD12345678", "")).isNull()
+        assertThat(G2SerialResolution.resolve(null, "NOT_SET", "NOT_SET")).isNull()
+    }
+
+    @Test
+    fun `switching to a different pair does not leak the previous serial`() {
+        assertThat(G2SerialResolution.resolve(null, "S2NEW000000001", "S2OLD000000000")).isNull()
+    }
+}

package/build/generated/changelogCatalog.d.ts

@@ -4,6 +4,6 @@ export declare const GENERATED_RELEASE_CHANGELOGS: readonly [{
     readonly markdown: "This release is under active development. User-facing changes will be documented as they land.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`.";
 }, {
     readonly version: "3.1.0";
-    readonly markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.";
+    readonly markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them.";
 }];
 //# sourceMappingURL=changelogCatalog.d.ts.map

package/build/generated/changelogCatalog.js

@@ -6,7 +6,7 @@ export const GENERATED_RELEASE_CHANGELOGS = Object.freeze([
     },
     {
         "version": "3.1.0",
-        "markdown": "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."
+        "markdown": "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them."
     }
 ]);
 //# sourceMappingURL=changelogCatalog.js.map