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

package/README.md

@@ -214,10 +214,19 @@ enterprise device deployments:
 
 - `bluetooth_sdk_started`: sent once per app runtime after the native SDK starts.
 - `bluetooth_sdk_glasses_connected`: sent when SDK status transitions from not connected to connected.
-- `bluetooth_sdk_glasses_identified`: sent once per connection after the SDK receives a valid manufacturing serial from the glasses. This fires for every supported model that reports a serial. G1 and Ar99 decode the serial from the glasses' BLE advertisement. Mentra Live reports the product serial provisioned by its Android firmware through `asg_client`.
+- `bluetooth_sdk_glasses_identified`: sent once per connection after the SDK receives a valid manufacturing serial from the glasses, and again as a `glasses_heartbeat` on the first status update of each new reporting day (`America/Los_Angeles` calendar day, the calendar Mentra's weekly reporting is cut on) while that connection is still up, so a connection that spans a week boundary is visible in both weeks. Heartbeats ride on glasses status updates; a connection whose status never changes for a whole day produces none. This fires for every supported model that reports a serial. G1, G2, and Ar99 decode the serial from the glasses' BLE advertisement. Mentra Live reports the product serial provisioned by its Android firmware through `asg_client`.
 
-Analytics delivery is fire-and-forget: events are submitted asynchronously, do
-not block Bluetooth SDK behavior, and are not retried if delivery fails.
+The connected event waits for the glasses model when the model is not known at
+the moment the connection flag flips; if the connection ends first it is sent
+without a model and with `glasses_model_unresolved=true`.
+
+Analytics delivery never blocks Bluetooth SDK behavior: events are submitted
+asynchronously off the caller thread. An upload that fails (no network, non-2xx)
+is kept in a small on-device queue (at most 100 events, 7 days) and retried on
+the next successful send or the next SDK start; a payload PostHog rejects
+outright (4xx other than 408/429) is dropped rather than retried. Each event
+carries its own `uuid` and capture `timestamp`, so a retry neither double counts
+nor moves the event to a later week.
 
 React Native / Expo apps can disable these events before SDK startup through
 the config plugin:
@@ -243,6 +252,21 @@ Native Android apps can pass `BluetoothSdkAnalyticsConfig.disabled()` in
 Native iOS apps can pass `.disabled` in `MentraBluetoothSDKConfiguration` or set
 `MentraBluetoothSdkAnalyticsDisabled` to `true` in `Info.plist`.
 
+Hosts that ship the same package id through several lanes (dev, staging, store)
+can label the lane so Mentra can separate them. Pass
+`{"analytics": {"environment": "prod"}}` to the config plugin, or set the
+`com.mentra.bluetoothsdk.analytics.environment` Android metadata /
+`MentraBluetoothSdkAnalyticsEnvironment` `Info.plist` key directly. Values are
+trimmed and lowercased, must start with a letter or digit, may then contain
+`[a-z0-9_-]`, are at most 32 characters, and are reported as `app_environment`.
+
+Mentra counts an install as production only when `app_install_source` is
+`app_store` or `play_store`, `app_build_type` is `release`, and, for hosts that
+declare a lane, `app_environment` is `prod`. Play cannot distinguish its testing
+tracks from production (both report `play_store`), so the lane is what separates
+them for the Mentra App; hosts without a lane are reported as an unclassified
+store cohort rather than assumed production.
+
 Mentra's PostHog project API key is embedded in the SDK as a public analytics
 write token, not a private PostHog personal API key. Apps do not configure the
 analytics destination; these SDK usage events are always sent to Mentra's
@@ -251,11 +275,24 @@ PostHog project unless analytics are disabled.
 Captured properties include `event_source`, `sdk_platform`, `sdk_surface`,
 `sdk_version`, `app_identifier` (the Android package or iOS bundle identifier),
 the platform-specific `app_package` or `app_bundle_identifier`, OS
-platform/version, and `event_kind`. Connection events also include
-`fully_booted` and a glasses model value when known. The identification event
-intentionally includes the glasses manufacturing serial as `glasses_device_id`,
-with `glasses_device_id_type=manufacturing_serial`, so Mentra can correlate
-fleet deployments across supported models. This serial identifies the glasses
+platform/version, and `event_kind`. Every event also carries host build facts:
+`app_version`, `app_build`, `app_build_type` (`debug` / `release`),
+`app_install_source` (`play_store`, `app_store`, `testflight`, `adhoc_or_dev`,
+`simulator`, `sideload`, a named third-party store, `other_store`, or `unknown`
+when the platform gave no usable evidence), the raw Android
+`app_installer_package` when present, and `app_environment` when the host
+declares one. Connection and identification events include `fully_booted`,
+a glasses model value when known, and `glasses_is_simulated`. The identification
+event intentionally includes the glasses manufacturing serial as
+`glasses_device_id`, with `glasses_device_id_type=manufacturing_serial`, so
+Mentra can correlate fleet deployments across supported models, plus the
+glasses-side software versions the SDK already holds (`glasses_firmware_version`,
+`glasses_bes_firmware_version`, `glasses_mtk_firmware_version`,
+`glasses_android_version`, `glasses_app_version`, `glasses_build_number`) so
+identified glasses can be grouped by firmware. Glasses that never report a
+serial produce no identification event; that coverage gap is measured as
+connections without identification per model and SDK version, not from these
+fields. This serial identifies the glasses
 hardware, not the user or the host phone. Its source depends on the model:
 Mentra Live reports the serial provisioned in BES NV storage, while G1 and Ar99
 decode it from the glasses' BLE advertisement / manufacturer data.

package/android/build.gradle

@@ -274,6 +274,8 @@ dependencies {
   testImplementation 'junit:junit:4.13.2'
   testImplementation 'org.robolectric:robolectric:4.11.1'
   testImplementation 'org.assertj:assertj-core:3.24.2'
+  // The Android SDK jar stubs org.json in JVM unit tests; the queue serializes real JSON.
+  testImplementation 'org.json:json:20240303'
   testImplementation 'androidx.test:core:1.5.0'
 
   // Local photo upload receiver

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

@@ -3,13 +3,15 @@ package com.mentra.bluetoothsdk
 import android.content.Context
 import android.content.pm.PackageManager
 import android.os.Build
+import com.mentra.bluetoothsdk.utils.DeviceTypes
 import org.json.JSONObject
 import java.net.HttpURLConnection
 import java.net.URL
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
 import java.util.UUID
-import java.util.concurrent.ExecutorService
-import java.util.concurrent.Executors
-import java.util.concurrent.RejectedExecutionException
 
 class BluetoothSdkAnalyticsConfig private constructor(
     val enabled: Boolean,
@@ -40,25 +42,23 @@ internal class BluetoothSdkAnalytics(
     initialConfig: BluetoothSdkAnalyticsConfig,
 ) {
     private val appContext = context.applicationContext
-    private val executor: ExecutorService = Executors.newSingleThreadExecutor { runnable ->
-        Thread(runnable, "MentraBluetoothSdkAnalytics").apply { isDaemon = true }
-    }
-    // startedCaptured/lastConnected are touched from store listeners and SDK
-    // entry points, hence @Synchronized on methods that read or write them.
     private val config = initialConfig.toRuntimeConfig().resolvedForApp(appContext)
+    // The tracker is touched from store listeners and SDK entry points, hence
+    // @Synchronized on the methods that read or write it.
+    private val tracker = BluetoothSdkAnalyticsTracker(DeviceTypes.SIMULATED)
     private var startedCaptured = false
-    private var lastConnected = false
-    private var identifiedCapturedForConnection = false
+    // Resolved once, lazily, on the transport executor: PackageManager lookups
+    // must not run on the caller (often main or the Bluetooth status) thread.
+    private val hostProperties: Map<String, Any> by lazy { BluetoothSdkAnalyticsHost.resolve(appContext).toMap() }
+    // The retry queue and its executor are process-wide (see BluetoothSdkAnalyticsTransport).
+    private val queue: BluetoothSdkAnalyticsQueue get() = BluetoothSdkAnalyticsTransport.queue(appContext)
+    private val isoFormat = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply {
+        timeZone = TimeZone.getTimeZone("UTC")
+    }
 
     @Synchronized
     fun initializeGlassesStatus(status: GlassesStatus) {
-        lastConnected = status.analyticsConnected
-        // 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 false so the identify event still fires once the serial arrives.
-        identifiedCapturedForConnection =
-            status.analyticsConnected && status.serialNumber.validManufacturingSerial() != null
+        tracker.initialize(status.toAnalyticsSnapshot(), BluetoothSdkAnalyticsTracker.reportingDay(System.currentTimeMillis()))
     }
 
     @Synchronized
@@ -66,52 +66,23 @@ internal class BluetoothSdkAnalytics(
         if (startedCaptured || !config.isReady) return
         startedCaptured = true
         capture("bluetooth_sdk_started", mapOf("event_kind" to "sdk_started"))
+        // A fresh runtime is the natural moment to retry what an earlier one could not deliver.
+        runOnExecutor { queue.drain(System.currentTimeMillis()) { payload -> send(payload) } }
     }
 
     @Synchronized
     fun observeGlassesStatus(status: GlassesStatus) {
-        val isConnected = status.analyticsConnected
-        val wasConnected = lastConnected
-        lastConnected = isConnected
+        val events = tracker.observe(status.toAnalyticsSnapshot(), BluetoothSdkAnalyticsTracker.reportingDay(System.currentTimeMillis()))
         if (!config.isReady) return
-        if (!isConnected) {
-            identifiedCapturedForConnection = false
-            return
-        }
-        if (isConnected && !wasConnected) {
-            identifiedCapturedForConnection = false
-            capture(
-                "bluetooth_sdk_glasses_connected",
-                buildMap {
-                    put("event_kind", "glasses_connected")
-                    put("fully_booted", status.fullyBooted)
-                    status.deviceModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
-                },
-            )
-            // Fall through: a serial already present at connect time (G1/Ar99 report
-            // it in the advertisement) should be identified now rather than waiting
-            // for some later, unrelated glasses-store update to run.
-        }
-
-        val serialNumber = status.serialNumber.validManufacturingSerial() ?: return
-        if (!identifiedCapturedForConnection) {
-            identifiedCapturedForConnection = true
-            capture(
-                "bluetooth_sdk_glasses_identified",
-                buildMap {
-                    put("event_kind", "glasses_identified")
-                    put("fully_booted", status.fullyBooted)
-                    put("glasses_device_id", serialNumber)
-                    put("glasses_device_id_type", "manufacturing_serial")
-                    status.deviceModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
-                },
-            )
-        }
+        for (event in events) capture(event.name, event.properties)
     }
 
-    fun shutdown() {
-        executor.shutdown()
-    }
+    /**
+     * Delivery is owned by the process-wide transport, so nothing is torn down
+     * here: a retry in flight when this instance closes still completes, and a
+     * replacement instance cannot race it on the retry file.
+     */
+    fun shutdown() {}
 
     private fun capture(
         eventName: String,
@@ -119,40 +90,60 @@ internal class BluetoothSdkAnalytics(
     ) {
         val activeConfig = config
         if (!activeConfig.isReady) return
+        // Identity and time are fixed at capture, not at (re)send, so a retried
+        // event neither double counts nor drifts into a later week.
+        val uuid = UUID.randomUUID().toString()
+        val capturedAt = System.currentTimeMillis()
+        runOnExecutor {
+            val payload =
+                JSONObject(
+                    mapOf(
+                        "api_key" to DEFAULT_POSTHOG_API_KEY,
+                        "uuid" to uuid,
+                        "event" to eventName,
+                        "distinct_id" to distinctId(),
+                        "timestamp" to isoFormat.format(Date(capturedAt)),
+                        "properties" to baseProperties(activeConfig) + hostProperties + eventProperties,
+                    )
+                )
+            when (send(payload)) {
+                SendOutcome.DELIVERED -> queue.drain(capturedAt) { queued -> send(queued) }
+                SendOutcome.RETRY -> queue.enqueue(payload, capturedAt)
+                SendOutcome.DISCARD -> Unit
+            }
+        }
+    }
+
+    private fun runOnExecutor(block: () -> Unit) {
+        BluetoothSdkAnalyticsTransport.submit(block)
+    }
 
+    /**
+     * 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 (network errors, 5xx, 408, 429) is worth retrying later.
+     */
+    private fun send(payload: JSONObject): SendOutcome =
         try {
-            // Payload construction stays on the executor: distinctId() reads
-            // SharedPreferences, which must not run on the caller (often main) thread.
-            executor.execute {
-                try {
-                    val payload =
-                        JSONObject(
-                            mapOf(
-                                "api_key" to DEFAULT_POSTHOG_API_KEY,
-                                "event" to eventName,
-                                "distinct_id" to distinctId(),
-                                "properties" to baseProperties(activeConfig) + eventProperties,
-                            )
-                        )
-                    val connection = URL(captureUrl()).openConnection() as HttpURLConnection
-                    connection.requestMethod = "POST"
-                    connection.connectTimeout = 4_000
-                    connection.readTimeout = 4_000
-                    connection.doOutput = true
-                    connection.setRequestProperty("Content-Type", "application/json")
-                    connection.outputStream.use { output ->
-                        output.write(payload.toString().toByteArray(Charsets.UTF_8))
-                    }
-                    connection.inputStream.close()
-                    connection.disconnect()
-                } catch (_: Exception) {
-                    // Analytics must never affect Bluetooth SDK behavior.
+            val connection = URL(captureUrl()).openConnection() as HttpURLConnection
+            try {
+                connection.requestMethod = "POST"
+                connection.connectTimeout = 4_000
+                connection.readTimeout = 4_000
+                connection.doOutput = true
+                connection.setRequestProperty("Content-Type", "application/json")
+                connection.outputStream.use { output ->
+                    output.write(payload.toString().toByteArray(Charsets.UTF_8))
                 }
+                val code = connection.responseCode
+                if (code in 200..299) connection.inputStream.close() else connection.errorStream?.close()
+                SendOutcome.fromHttpStatus(code)
+            } finally {
+                connection.disconnect()
             }
-        } catch (_: RejectedExecutionException) {
-            // The executor was shut down (SDK closed); dropping the event is fine.
+        } catch (_: Exception) {
+            SendOutcome.RETRY
         }
-    }
 
     private fun baseProperties(activeConfig: BluetoothSdkAnalyticsRuntimeConfig): Map<String, Any> =
         buildMap {
@@ -209,8 +200,16 @@ private fun BluetoothSdkAnalyticsRuntimeConfig.resolvedForApp(context: Context):
     )
 }
 
-private val GlassesStatus.analyticsConnected: Boolean
-    get() = connectionState.isConnected || connected || fullyBooted
-
-private fun String.validManufacturingSerial(): String? =
-    trim().takeIf { it.isNotEmpty() && !it.matches(Regex("0+")) }
+private fun GlassesStatus.toAnalyticsSnapshot(): AnalyticsGlassesSnapshot =
+    AnalyticsGlassesSnapshot(
+        connected = connectionState.isConnected || connected || fullyBooted,
+        fullyBooted = fullyBooted,
+        model = deviceModel,
+        serialNumber = serialNumber,
+        firmwareVersion = firmwareVersion,
+        besFirmwareVersion = besFirmwareVersion,
+        mtkFirmwareVersion = mtkFirmwareVersion,
+        androidVersion = androidVersion,
+        appVersion = appVersion,
+        buildNumber = buildNumber,
+    )

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

@@ -0,0 +1,106 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import android.content.pm.PackageManager
+import android.os.Build
+
+/**
+ * Host-app facts attached to every analytics event so Mentra can separate store
+ * installs from sideloaded, debuggable, and internal-lane builds.
+ */
+internal data class BluetoothSdkAnalyticsHostProperties(
+    val appVersion: String?,
+    val appBuild: String?,
+    val buildType: String,
+    val installSource: String,
+    val installerPackage: String?,
+    val environment: String?,
+) {
+    fun toMap(): Map<String, Any> =
+        buildMap {
+            appVersion?.let { put("app_version", it) }
+            appBuild?.let { put("app_build", it) }
+            put("app_build_type", buildType)
+            put("app_install_source", installSource)
+            installerPackage?.let { put("app_installer_package", it) }
+            environment?.let { put("app_environment", it) }
+        }
+}
+
+internal object BluetoothSdkAnalyticsHost {
+    /**
+     * Optional host-declared lane (`dev`, `staging`, `prod`, ...). Stamped by the Expo
+     * config plugin's `analytics.environment` option; native apps may set it directly.
+     */
+    const val META_ENVIRONMENT = "com.mentra.bluetoothsdk.analytics.environment"
+
+    private val environmentPattern = Regex("^[a-z0-9][a-z0-9_-]{0,31}$")
+
+    /**
+     * Android cannot tell a Play production install from a Play testing track: both
+     * arrive through `com.android.vending`. `app_environment` is the host's way to
+     * add that distinction. A missing installer is documented to mean adb, a file
+     * manager, or an IDE put the APK on the device; a failed lookup is reported as
+     * `unknown` rather than guessed, because this value decides whether an install
+     * counts as production.
+     */
+    fun installSourceFor(installerPackage: String?, lookupFailed: Boolean = false): String =
+        when {
+            lookupFailed -> "unknown"
+            else -> installerPackage?.trim()?.takeIf { it.isNotEmpty() }.let { installer ->
+                when (installer) {
+                    null -> "sideload"
+                    "com.android.vending" -> "play_store"
+                    "com.amazon.venezia" -> "amazon_appstore"
+                    "com.sec.android.app.samsungapps" -> "galaxy_store"
+                    "com.huawei.appmarket" -> "huawei_appgallery"
+                    "com.xiaomi.market" -> "xiaomi_getapps"
+                    else -> "other_store"
+                }
+            }
+        }
+
+    fun normalizedEnvironment(raw: String?): String? =
+        raw?.trim()?.lowercase()?.takeIf { environmentPattern.matches(it) }
+
+    fun resolve(context: Context): BluetoothSdkAnalyticsHostProperties {
+        val packageManager = context.packageManager
+        val packageName = context.packageName
+        val packageInfo =
+            try {
+                packageManager.getPackageInfo(packageName, 0)
+            } catch (_: Exception) {
+                null
+            }
+        val applicationInfo =
+            try {
+                packageManager.getApplicationInfo(packageName, PackageManager.GET_META_DATA)
+            } catch (_: Exception) {
+                null
+            }
+        var installerLookupFailed = false
+        val installer =
+            try {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                    packageManager.getInstallSourceInfo(packageName).installingPackageName
+                } else {
+                    @Suppress("DEPRECATION")
+                    packageManager.getInstallerPackageName(packageName)
+                }
+            } catch (_: Exception) {
+                installerLookupFailed = true
+                null
+            }
+        val debuggable = ((applicationInfo?.flags ?: 0) and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+
+        return BluetoothSdkAnalyticsHostProperties(
+            appVersion = packageInfo?.versionName?.trim()?.takeIf { it.isNotEmpty() },
+            appBuild = packageInfo?.longVersionCode?.toString(),
+            buildType = if (debuggable) "debug" else "release",
+            installSource = installSourceFor(installer, installerLookupFailed),
+            installerPackage = installer?.trim()?.takeIf { it.isNotEmpty() },
+            environment = normalizedEnvironment(applicationInfo?.metaData?.getString(META_ENVIRONMENT)),
+        )
+    }
+}

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

@@ -0,0 +1,111 @@
+package com.mentra.bluetoothsdk
+
+import org.json.JSONObject
+import java.io.File
+
+internal enum class SendOutcome {
+    DELIVERED,
+    RETRY,
+    DISCARD,
+    ;
+
+    companion object {
+        fun fromHttpStatus(code: Int): SendOutcome =
+            when {
+                code in 200..299 -> DELIVERED
+                code == 408 || code == 429 -> RETRY
+                code in 400..499 -> DISCARD
+                else -> 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 [maxAgeMillis] 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 executor.
+ */
+internal class BluetoothSdkAnalyticsQueue(
+    private val file: File,
+    private val maxEntries: Int = DEFAULT_MAX_ENTRIES,
+    private val maxAgeMillis: Long = DEFAULT_MAX_AGE_MILLIS,
+) {
+    fun enqueue(payload: JSONObject, nowMillis: Long) {
+        val entries = read().toMutableList()
+        entries += JSONObject().put("enqueued_at", nowMillis).put("payload", payload)
+        while (entries.size > maxEntries) entries.removeAt(0)
+        write(entries)
+    }
+
+    fun size(): Int = read().size
+
+    /**
+     * 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.
+     */
+    fun drain(nowMillis: Long, send: (JSONObject) -> SendOutcome) {
+        val entries = read()
+        if (entries.isEmpty()) return
+        val remaining = mutableListOf<JSONObject>()
+        var blocked = false
+        for (entry in entries) {
+            val enqueuedAt = entry.optLong("enqueued_at", nowMillis)
+            if (nowMillis - enqueuedAt > maxAgeMillis) continue
+            val payload = entry.optJSONObject("payload") ?: continue
+            if (blocked) {
+                remaining += entry
+                continue
+            }
+            val outcome =
+                try {
+                    send(payload)
+                } catch (_: Exception) {
+                    SendOutcome.RETRY
+                }
+            if (outcome == SendOutcome.RETRY) {
+                blocked = true
+                remaining += entry
+            }
+        }
+        write(remaining)
+    }
+
+    private fun read(): List<JSONObject> {
+        if (!file.exists()) return emptyList()
+        return try {
+            file.readLines().mapNotNull { line ->
+                line.takeIf { it.isNotBlank() }?.let { runCatching { JSONObject(it) }.getOrNull() }
+            }
+        } catch (_: Exception) {
+            emptyList()
+        }
+    }
+
+    private fun write(entries: List<JSONObject>) {
+        try {
+            if (entries.isEmpty()) {
+                file.delete()
+                return
+            }
+            file.parentFile?.mkdirs()
+            val tmp = File(file.parentFile, file.name + ".tmp")
+            tmp.writeText(entries.joinToString("\n") { it.toString() } + "\n")
+            if (!tmp.renameTo(file)) {
+                file.writeText(entries.joinToString("\n") { it.toString() } + "\n")
+                tmp.delete()
+            }
+        } catch (_: Exception) {
+            // A queue write failure only loses retries, never live behavior.
+        }
+    }
+
+    companion object {
+        const val DEFAULT_MAX_ENTRIES = 100
+        const val DEFAULT_MAX_AGE_MILLIS = 7L * 24 * 60 * 60 * 1000
+        const val FILE_NAME = "mentra_bluetooth_sdk_analytics_queue.jsonl"
+    }
+}