@mentra/bluetooth-sdk 0.1.11 → 0.1.13

package/README.md

@@ -150,6 +150,55 @@ uses a CoreBluetooth identifier when available, and the SDK falls back to
 platform reports RSSI, so picker UI should handle `undefined` and avoid
 reordering rows just because RSSI metadata arrives later.
 
+## Mentra SDK Usage Analytics
+
+The SDK sends two anonymous usage events to Mentra's PostHog project by default
+so Mentra can understand SDK adoption and successful glasses connections:
+
+- `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.
+
+Analytics delivery is fire-and-forget: events are submitted asynchronously, do
+not block Bluetooth SDK behavior, and are not retried if delivery fails.
+
+React Native / Expo apps can disable these events before SDK startup through
+the config plugin:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@mentra/bluetooth-sdk",
+        {
+          "analytics": false
+        }
+      ]
+    ]
+  }
+}
+```
+
+Native Android apps can pass `BluetoothSdkAnalyticsConfig.disabled()` in
+`MentraBluetoothSdkConfig` or add
+`com.mentra.bluetoothsdk.analytics.disabled=true` as application metadata.
+Native iOS apps can pass `.disabled` in `MentraBluetoothSDKConfiguration` or set
+`MentraBluetoothSdkAnalyticsDisabled` to `true` in `Info.plist`.
+
+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
+PostHog project unless analytics are disabled.
+
+Captured properties are limited to non-sensitive SDK/app metadata:
+`event_source`, `sdk_platform`, `sdk_surface`, `sdk_version`, the app package or
+bundle identifier, OS platform/version, `event_kind`, and for connection events
+only `fully_booted` plus a glasses model value when the SDK knows it. The SDK
+does not upload BLE MAC addresses, CoreBluetooth identifiers, serial numbers,
+Bluetooth device names, user ids, tokens, Wi-Fi credentials, microphone data,
+photos, or transcripts. PostHog receives a locally generated anonymous SDK
+install id as `distinct_id`, and events include `$process_person_profile: false`.
+
 ## React Hooks
 
 React Native apps can import optional lifecycle helpers from the `react`
@@ -274,9 +323,9 @@ React Native narrows returned values to success shapes where the raw listener ev
 | --- | --- | --- |
 | `requestPhoto(...)` | Terminal `PhotoSuccessResponseEvent` with `state: "success"` after capture and delivery finish. `uploadUrl` is always present; webhook JSON metadata such as `photoUrl`, `statusUrl`, `contentType`, or `fileSizeBytes` is included when the receiver returns it. | Rejects when raw `photo_response.state === "error"`, the SDK cannot send the command, or the terminal photo response times out. |
 | `startVideoRecording(...)` | `VideoRecordingStartedStatusEvent` with `success: true` and `status: "recording_started"`. | Rejects on `success: false` statuses such as `already_recording`, send failure, or timeout. |
-| `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. | Rejects on `success: false` statuses such as `not_recording`, send failure, or timeout. |
+| `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. When a webhook URL is supplied, resolves after the video upload succeeds. | Rejects on `success: false` statuses such as `not_recording`, webhook upload failure, send failure, or timeout. |
 | `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
-| `checkForOtaUpdate()` / `retryOtaVersionCheck()` | `OtaQueryResult`, either `ota_update_available` or current `ota_status`. | Rejects on command transport timeout/failure. A returned `ota_status.status === "failed"` is glasses OTA state, not a command rejection. |
+| `checkForOtaUpdate()` | `boolean`, true when the configured OTA manifest has an ASG APK, MTK, or BES update for the connected glasses; false only when the manifest was checked successfully and no update is available. | Rejects when the glasses are disconnected, version info is unavailable, the manifest cannot be fetched, or the manifest response is invalid/missing required ASG app version fields. |
 
 Android and iOS async APIs use `BluetoothException` / `BluetoothError` for the same error paths. Their returned event structs are the successful response in normal `try`/`await` code, while raw listener/delegate events still include both success and error payloads.
 
@@ -286,9 +335,16 @@ Android and iOS async APIs use `BluetoothException` / `BluetoothError` for the s
 
 Mentra Live firmware owns the OTA flow. The SDK mirrors the MentraOS app commands and events:
 
-- `checkForOtaUpdate()` sends `ota_query_status` and resolves with the ASG response (`ota_update_available` or the current `ota_status`).
-- `startOtaUpdate()` sends `ota_start` and resolves with the ASG start ack after your app presents the update and the user accepts it.
-- `retryOtaVersionCheck()` sends `ota_retry_version_check` and resolves with the same ASG response shape as `checkForOtaUpdate()`; use it only after fixing a known clock-skew/TLS failure.
+- `checkForOtaUpdate()` fetches the configured manifest and resolves with `true` when an ASG APK, MTK, or BES update is available.
+- `startOtaUpdate()` sends `ota_start` with the same configured manifest URL and resolves with the ASG start ack after your app presents the update and the user accepts it.
+
+The default manifest is derived from the SDK version:
+`https://github.com/Mentra-Community/MentraOS/releases/download/bluetooth-sdk-ota/bluetooth-sdk-<sdkVersion>-version.json`.
+Each published SDK version points at a durable ASG client APK and firmware
+manifest that were built for that SDK release. Pre-wall-clock ASG builds that
+ignore `ota_start.ota_version_url` are checked against the URL they advertise,
+or the production default if they do not advertise one, so the app does not
+prompt for an update the glasses cannot install.
 
 ```ts
 import BluetoothSdk from '@mentra/bluetooth-sdk'
@@ -297,9 +353,9 @@ BluetoothSdk.addListener('ota_status', (event) => {
   console.log(`OTA ${event.status}: ${event.overall_percent}%`)
 })
 
-const ota = await BluetoothSdk.checkForOtaUpdate()
-if (ota.type === 'ota_update_available') {
-  const userAccepted = await promptUserToInstallUpdate(ota) // your app's UI
+const hasUpdate = await BluetoothSdk.checkForOtaUpdate()
+if (hasUpdate) {
+  const userAccepted = await promptUserToInstallUpdate() // your app's UI
   if (userAccepted) {
     const startAck = await BluetoothSdk.startOtaUpdate()
     console.log('OTA start acknowledged', startAck.timestamp)
@@ -332,7 +388,7 @@ For one-shot manual capture tuning, pass `exposureTimeNs` and `iso` together. `e
 
 Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 62-118 degrees; ROI position is `"center"`, `"bottom"`, or `"top"`. You can also call `setCameraFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. The returned `CameraFovResult` resolves only after the ASG client reports that the setting was applied to camera hardware after the restart cooldown, and the promise rejects if the glasses report an error, persist the setting without hardware application, or time out. Raw `settings_ack` events remain available through `addListener("settings_ack", ...)` for diagnostic fields such as `hardwareApplied`. Treat FOV as a framing/ROI control; output resolution and effective detail can vary by capture path, firmware, and camera mode.
 
-`startVideoRecording(...)` and `stopVideoRecording(...)` resolve from successful ASG `video_recording_status` events only when the status matches the requested operation (`recording_started` or `recording_stopped`) and reject when the ASG reports `success: false`. Raw `video_recording_status` events remain available through listeners, including `recording_status` query events with `data.recording`.
+`startVideoRecording(...)` resolves from the ASG `video_recording_status` event whose status is `recording_started`. `stopVideoRecording(...)` without a webhook resolves from `recording_stopped`; with a webhook it waits for `recording_stopped` plus a video `media_success`, and rejects on `media_error`. Raw `video_recording_status`, `media_success`, and `media_error` events remain available through listeners.
 
 ## Streaming
 
@@ -376,7 +432,7 @@ export function HardwareEventLogger() {
 
 For non-React modules, `BluetoothSdk.addListener(...)` is the low-level subscription API. Keep the returned subscription and call `remove()` when the listener is no longer needed.
 
-Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_update_available`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
+Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
 
 React Native event payload fields usually use camelCase. OTA events intentionally mirror the glasses firmware field names, such as `overall_percent` and `version_name`. For example, `touch_event` includes `gestureName`, `wifi_scan_result` includes `networks` and `scanComplete`, `version_info` matches the `requestVersionInfo()` result shape, `photo_response` success includes `uploadUrl` and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, and `fileSizeBytes`, and `gallery_status` includes `hasContent`, `cameraBusy`, and optional `cameraBusyReason`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `ble_fallback_compression`, `uploading`, `ready_for_transfer`, `transferring`, and `failed`; the `configuring` event includes `resolvedConfig` with the effective JPEG dimensions, quality, requested size, transfer method, compression, and manual exposure fields when present. The `capturing` event may include `requestedCaptureConfig` and `meteredPreview`; the `captured` event may include `captureMetadata` with the HAL-applied exposure, ISO, frame duration, and AE state. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
 
@@ -409,7 +465,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Add the `MentraBluetoothSDK` product to your app target at version `0.1.11` or newer.
+Select version `0.1.13`, then add the `MentraBluetoothSDK` product to your app target.
 
 For local SDK development, add this package folder directly in Xcode:
 

package/android/build.gradle

@@ -213,6 +213,7 @@ android {
   defaultConfig {
     versionCode 1
     versionName project.version
+    buildConfigField "String", "SDK_VERSION", "\"${project.version}\""
   }
   publishing {
     singleVariant("release") {

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

@@ -0,0 +1,182 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+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,
+    internal val surface: String,
+) {
+    @JvmOverloads
+    constructor(enabled: Boolean = true) : this(enabled, "android")
+
+    internal fun withSurface(surface: String): BluetoothSdkAnalyticsConfig =
+        BluetoothSdkAnalyticsConfig(enabled, surface)
+
+    companion object {
+        @JvmStatic
+        fun disabled(): BluetoothSdkAnalyticsConfig = BluetoothSdkAnalyticsConfig(enabled = false)
+    }
+}
+
+private data class BluetoothSdkAnalyticsRuntimeConfig(
+    val enabled: Boolean = true,
+    val surface: String = "android",
+) {
+    val isReady: Boolean
+        get() = enabled
+}
+
+internal class BluetoothSdkAnalytics(
+    private val context: Context,
+    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)
+    private var startedCaptured = false
+    private var lastConnected = false
+
+    @Synchronized
+    fun initializeGlassesStatus(status: GlassesStatus) {
+        lastConnected = status.analyticsConnected
+    }
+
+    @Synchronized
+    fun captureStarted() {
+        if (startedCaptured || !config.isReady) return
+        startedCaptured = true
+        capture("bluetooth_sdk_started", mapOf("event_kind" to "sdk_started"))
+    }
+
+    @Synchronized
+    fun observeGlassesStatus(status: GlassesStatus) {
+        val isConnected = status.analyticsConnected
+        val wasConnected = lastConnected
+        lastConnected = isConnected
+        if (!config.isReady) return
+        if (isConnected && !wasConnected) {
+            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) }
+                },
+            )
+        }
+    }
+
+    fun shutdown() {
+        executor.shutdown()
+    }
+
+    private fun capture(
+        eventName: String,
+        eventProperties: Map<String, Any>,
+    ) {
+        val activeConfig = config
+        if (!activeConfig.isReady) return
+
+        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.
+                }
+            }
+        } catch (_: RejectedExecutionException) {
+            // The executor was shut down (SDK closed); dropping the event is fine.
+        }
+    }
+
+    private fun baseProperties(activeConfig: BluetoothSdkAnalyticsRuntimeConfig): Map<String, Any> =
+        buildMap {
+            put("\$process_person_profile", false)
+            put("event_source", "mentra_bluetooth_sdk")
+            put("sdk_platform", "android")
+            put("sdk_surface", activeConfig.surface)
+            put("sdk_version", BuildConfig.SDK_VERSION)
+            put("app_package", appContext.packageName)
+            put("os_platform", "android")
+            put("os_version", Build.VERSION.SDK_INT)
+        }
+
+    private fun distinctId(): String {
+        val prefs = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        prefs.getString(PREFS_DISTINCT_ID, null)?.let { return it }
+        val generated = "mentra-bt-sdk-${UUID.randomUUID()}"
+        prefs.edit().putString(PREFS_DISTINCT_ID, generated).apply()
+        return generated
+    }
+
+    private fun captureUrl(): String {
+        val normalized = DEFAULT_POSTHOG_HOST.trim().trimEnd('/')
+        return "$normalized/i/v0/e/"
+    }
+
+    companion object {
+        internal const val META_ANALYTICS_DISABLED = "com.mentra.bluetoothsdk.analytics.disabled"
+        private const val PREFS_NAME = "mentra_bluetooth_sdk_analytics"
+        private const val PREFS_DISTINCT_ID = "distinct_id"
+        private const val DEFAULT_POSTHOG_API_KEY = "phc_FCweXVAxVgU7wZK4Fk3okOx4RmyNqVHJf62YpZSfJt5"
+        private const val DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com"
+    }
+}
+
+private fun BluetoothSdkAnalyticsConfig.toRuntimeConfig(): BluetoothSdkAnalyticsRuntimeConfig =
+    BluetoothSdkAnalyticsRuntimeConfig(enabled = enabled, surface = surface)
+
+private fun BluetoothSdkAnalyticsRuntimeConfig.resolvedForApp(context: Context): BluetoothSdkAnalyticsRuntimeConfig {
+    val metadata =
+        try {
+            context.packageManager
+                .getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+                .metaData
+        } catch (_: Exception) {
+            null
+        }
+
+    val disabledByApp = metadata?.getBoolean(BluetoothSdkAnalytics.META_ANALYTICS_DISABLED, false) == true
+
+    return copy(
+        enabled = enabled && !disabledByApp,
+    )
+}
+
+private val GlassesStatus.analyticsConnected: Boolean
+    get() = connectionState.isConnected || connected || fullyBooted

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

@@ -120,6 +120,10 @@ class BluetoothSdkModule : Module() {
                     sendEvent("video_recording_status", event.values)
                 }
 
+                override fun onMediaUpload(event: MediaUploadEvent) {
+                    sendEvent(event.type, event.values)
+                }
+
                 override fun onRgbLedControlResponse(event: RgbLedControlResponseEvent) {
                     sendEvent("rgb_led_control_response", event.values)
                 }
@@ -213,6 +217,8 @@ class BluetoothSdkModule : Module() {
             "photo_response",
             "photo_status",
             "video_recording_status",
+            "media_success",
+            "media_error",
             "gallery_status",
             "compatible_glasses_search_stop",
             "heartbeat_sent",
@@ -256,7 +262,14 @@ class BluetoothSdkModule : Module() {
                             ?: appContext.currentActivity
                                     ?: throw IllegalStateException("No context available")
             BleTraceLogger.logLifecycle(context, "BluetoothSdkModule", "module_create")
-            sdk = MentraBluetoothSdk.create(context, sdkListener)
+            sdk =
+                    MentraBluetoothSdk.create(
+                            context,
+                            MentraBluetoothSdkConfig(
+                                    analytics = BluetoothSdkAnalyticsConfig().withSurface("react_native")
+                            ),
+                            sdkListener,
+                    )
             deviceManager = DeviceManager.getInstance()
         }
 
@@ -428,8 +441,37 @@ class BluetoothSdkModule : Module() {
             sdk?.setVoiceActivityDetectionEnabled(enabled)
         }
 
-        AsyncFunction("setButtonPhotoSettings") { size: String ->
-            requireSdk().setButtonPhotoSettings(ButtonPhotoSize.fromValue(size)).values
+        AsyncFunction("setButtonPhotoCaptureSettings") { params: Map<String, Any?> ->
+            val size = (params["size"] as? String)?.let { ButtonPhotoSize.fromValue(it) }
+            val mfnr = params["mfnr"] as? Boolean
+            val zsl = params["zsl"] as? Boolean
+            val noiseReduction = params["noiseReduction"] as? Boolean
+            val edgeEnhancement = params["edgeEnhancement"] as? Boolean
+            val ispDigitalGain = (params["ispDigitalGain"] as? Number)?.toInt()
+            val ispAnalogGain = params["ispAnalogGain"] as? String
+            val aeExposureDivisor = (params["aeExposureDivisor"] as? Number)?.toInt()
+            val isoCap = (params["isoCap"] as? Number)?.toInt()
+            val compress = params["compress"] as? String
+            val sound = params["sound"] as? Boolean
+            val resetCaptureTuning = params["resetCaptureTuning"] as? Boolean == true
+            requireSdk()
+                .setButtonPhotoSettings(
+                    ButtonPhotoSettings(
+                        size = size,
+                        mfnr = mfnr,
+                        zsl = zsl,
+                        noiseReduction = noiseReduction,
+                        edgeEnhancement = edgeEnhancement,
+                        ispDigitalGain = ispDigitalGain,
+                        ispAnalogGain = ispAnalogGain,
+                        aeExposureDivisor = aeExposureDivisor,
+                        isoCap = isoCap,
+                        compress = compress,
+                        sound = sound,
+                        resetCaptureTuning = resetCaptureTuning,
+                    ),
+                )
+                .values
         }
 
         AsyncFunction("setButtonVideoRecordingSettings") { width: Int, height: Int, fps: Int ->
@@ -470,7 +512,26 @@ class BluetoothSdkModule : Module() {
 
         // MARK: - OTA Commands
 
-        AsyncFunction("sendOtaStart") { requireSdk().sendOtaStart().values }
+        Function("setOtaVersionUrl") { otaVersionUrl: String ->
+            requireSdk().setOtaVersionUrl(otaVersionUrl)
+        }
+
+        Function("getOtaVersionUrl") { requireSdk().getOtaVersionUrl() }
+
+        // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue:
+        // manifest fetches and version waits can block for several seconds.
+        AsyncFunction("checkForOtaUpdate") Coroutine { ->
+            withContext(Dispatchers.IO) { requireSdk().checkForOtaUpdate() }
+        }
+
+        AsyncFunction("startOtaUpdate") { otaVersionUrl: String? ->
+            val sdk = requireSdk()
+            if (otaVersionUrl.isNullOrBlank()) {
+                sdk.startOtaUpdate().values
+            } else {
+                sdk.startOtaUpdate(otaVersionUrl).values
+            }
+        }
 
         AsyncFunction("sendOtaQueryStatus") { requireSdk().sendOtaQueryStatus().values }
 
@@ -505,12 +566,18 @@ class BluetoothSdkModule : Module() {
                             dim("width"),
                             dim("height"),
                             dim("fps"),
+                            dim("maxRecordingTimeMinutes"),
                     )
             ).values
         }
 
-        AsyncFunction("stopVideoRecording") { requestId: String ->
-            requireSdk().stopVideoRecording(requestId).values
+        // webhookUrl/authToken are supplied at stop (not start) so the token is
+        // fresh when the upload runs. Empty/null webhook = keep on device.
+        AsyncFunction("stopVideoRecording") {
+                requestId: String,
+                webhookUrl: String?,
+                authToken: String? ->
+            requireSdk().stopVideoRecording(requestId, webhookUrl, authToken).values
         }
 
         // MARK: - Stream Commands

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

@@ -417,6 +417,16 @@ public class Bridge private constructor() {
             sendTypedMessage("video_recording_status", body)
         }
 
+        @JvmStatic
+        fun sendMediaUploadEvent(type: String, values: Map<String, Any>) {
+            val body = HashMap<String, Any>()
+            body["type"] = type
+            values.forEach { (key, value) ->
+                body[key] = value
+            }
+            sendTypedMessage(type, body)
+        }
+
         @JvmStatic
         fun sendVersionInfo(values: Map<String, Any>) {
             fun stringField(vararg keys: String): String =