@bricks-soft/capacitor-location-tracking 8.0.1 → 8.2.0

package/android/src/main/java/com/brickssoft/locationtracking/model/DeviceModels.kt

@@ -139,7 +139,17 @@ data class HeartbeatStatus(
 
 // ---- device
 
-/** JS `DeviceInfo`. */
+/**
+ * JS `DeviceInfo`.
+ *
+ * @property backendFallbackReason why a better location backend is not used (recommendation 15), or null.
+ * @property gmsStatus `GoogleApiAvailability` result code (0 = SUCCESS), null if GMS is not packaged or not checked.
+ * @property hmsStatus `HuaweiApiAvailability` result code (0 = SUCCESS), null if HMS is not packaged or not checked.
+ * @property hmsCoreOutdated true when HMS Core is older than 6.3.0.301; null if HMS is not packaged.
+ * @property locationAvailableHint the last `LocationAvailability` of GMS or HMS; a hint, null if none was reported.
+ * @property cpuCores `Runtime.availableProcessors()`.
+ * @property supportedAbis `Build.SUPPORTED_ABIS`.
+ */
 data class DeviceInfo(
     val platform: String = "android",
     val manufacturer: String,
@@ -152,8 +162,41 @@ data class DeviceInfo(
     val hmsAvailable: Boolean,
     val backend: ProviderKind,
     val packagedProviders: List<String>,
+    val backendFallbackReason: String? = null,
+    val gmsStatus: Int? = null,
+    val hmsStatus: Int? = null,
+    val hmsCoreOutdated: Boolean? = null,
+    val locationAvailableHint: Boolean? = null,
+    val cpuCores: Int = 0,
+    val supportedAbis: List<String> = emptyList(),
 )
 
+/**
+ * The `device` object of records (see `DeviceDetails`); a null field is not written. Every record: [deviceId].
+ * Heartbeat: [backgroundRestricted], [standbyBucket], [diskFreeBytes], [thermalStatus]. `tracking_start`:
+ * [manufacturer], [model], [osVersion], [sdkInt], [lowRamDevice], [ramTotalBytes].
+ *
+ * @property deviceId the device id: `Settings.Secure.ANDROID_ID` on Android; null in records queued by an older version.
+ */
+data class DeviceSnapshot(
+    val backgroundRestricted: Boolean? = null,
+    val standbyBucket: String? = null,
+    val diskFreeBytes: Long? = null,
+    val thermalStatus: String? = null,
+    val manufacturer: String? = null,
+    val model: String? = null,
+    val osVersion: String? = null,
+    val sdkInt: Int? = null,
+    val deviceId: String? = null,
+    val lowRamDevice: Boolean? = null,
+    val ramTotalBytes: Long? = null,
+) {
+    val isEmpty: Boolean get() = this == DeviceSnapshot()
+}
+
+/** Battery readings added to the `battery` object of heartbeat records: °C, health and power source. */
+data class BatteryDetails(val temperature: Float?, val health: String?, val plugged: String?)
+
 /** JS `Sensors`. */
 data class Sensors(
     val accelerometer: Boolean,

package/android/src/main/java/com/brickssoft/locationtracking/model/ModelJson.kt

@@ -118,13 +118,18 @@ object RecordJson {
             "activity",
             JSONObject().put("type", record.activity.type.wire).put("confidence", record.activity.confidence),
         )
-        json.put(
-            "battery",
-            JSONObject()
-                .put("level", JsonUtil.floatOrNull(record.battery.level))
-                .put("is_charging", record.battery.isCharging),
-        )
+        val battery = JSONObject()
+            .put("level", JsonUtil.floatOrNull(record.battery.level))
+            .put("is_charging", record.battery.isCharging)
+        record.batteryDetails?.let { details ->
+            details.temperature?.let { battery.put("temperature", JsonUtil.floatOrNull(it)) }
+            details.health?.let { battery.put("health", it) }
+            details.plugged?.let { battery.put("plugged", it) }
+        }
+        json.put("battery", battery)
         json.put("backend", record.backend?.wire ?: JSONObject.NULL)
+        record.network?.let { json.put("network", it.wire) }
+        record.device?.takeUnless { it.isEmpty }?.let { json.put("device", deviceToJson(it)) }
         if (record.extras != null) {
             val extras = JsonUtil.parseObject(record.extras)
             if (extras != null) json.put("extras", extras) else Logger.w(TAG, "dropping invalid extras of ${record.uuid}")
@@ -133,9 +138,42 @@ object RecordJson {
         record.provider?.let { json.put("provider", ProviderStateJson.toJson(it)) }
         record.reason?.let { json.put("reason", it) }
         record.heartbeat?.let { json.put("heartbeat", heartbeatMetaToJson(it)) }
+        record.stoppedAt?.let { json.put("stopped_at", Iso8601.format(it)) }
+        return json
+    }
+
+    /** The `device` object of a record: only the readings that are set. */
+    fun deviceToJson(d: DeviceSnapshot): JSONObject {
+        val json = JSONObject()
+        d.deviceId?.let { json.put("device_id", it) }
+        d.backgroundRestricted?.let { json.put("background_restricted", it) }
+        d.standbyBucket?.let { json.put("standby_bucket", it) }
+        d.diskFreeBytes?.let { json.put("disk_free_bytes", it) }
+        d.thermalStatus?.let { json.put("thermal_status", it) }
+        d.manufacturer?.let { json.put("manufacturer", it) }
+        d.model?.let { json.put("model", it) }
+        d.osVersion?.let { json.put("os_version", it) }
+        d.sdkInt?.let { json.put("sdk_int", it) }
+        d.lowRamDevice?.let { json.put("low_ram_device", it) }
+        d.ramTotalBytes?.let { json.put("ram_total_bytes", it) }
         return json
     }
 
+    private fun deviceFromJson(json: JSONObject): DeviceSnapshot = DeviceSnapshot(
+        backgroundRestricted = JsonUtil.optBoolean(json, "background_restricted"),
+        standbyBucket = JsonUtil.optString(json, "standby_bucket"),
+        diskFreeBytes = JsonUtil.optLong(json, "disk_free_bytes"),
+        thermalStatus = JsonUtil.optString(json, "thermal_status"),
+        manufacturer = JsonUtil.optString(json, "manufacturer"),
+        model = JsonUtil.optString(json, "model"),
+        osVersion = JsonUtil.optString(json, "os_version"),
+        sdkInt = JsonUtil.optInt(json, "sdk_int"),
+        // `android_id`: the name before the rename, in tracking_start records queued by earlier round-3 builds
+        deviceId = JsonUtil.optString(json, "device_id") ?: JsonUtil.optString(json, "android_id"),
+        lowRamDevice = JsonUtil.optBoolean(json, "low_ram_device"),
+        ramTotalBytes = JsonUtil.optLong(json, "ram_total_bytes"),
+    )
+
     /** The `heartbeat` object of a heartbeat record (snake_case keys, `next_at` ISO-8601 or null). */
     fun heartbeatMetaToJson(meta: HeartbeatMeta): JSONObject = JSONObject()
         .put("strategy", meta.strategy.wire)
@@ -203,12 +241,20 @@ object RecordJson {
                 confidence = JsonUtil.optInt(it, "confidence") ?: 0,
             )
         } ?: ActivitySample.UNKNOWN
-        val battery = json.optJSONObject("battery")?.let {
+        val batteryJson = json.optJSONObject("battery")
+        val battery = batteryJson?.let {
             BatterySnapshot(
                 level = JsonUtil.optFloat(it, "level") ?: -1f,
                 isCharging = JsonUtil.optBoolean(it, "is_charging") ?: false,
             )
         } ?: BatterySnapshot.UNKNOWN
+        val batteryDetails = batteryJson?.let {
+            BatteryDetails(
+                temperature = JsonUtil.optFloat(it, "temperature"),
+                health = JsonUtil.optString(it, "health"),
+                plugged = JsonUtil.optString(it, "plugged"),
+            )
+        }?.takeUnless { it.temperature == null && it.health == null && it.plugged == null }
         return Record(
             uuid = uuid,
             event = event,
@@ -226,6 +272,10 @@ object RecordJson {
             provider = json.optJSONObject("provider")?.let { ProviderStateJson.fromJson(it) },
             reason = JsonUtil.optString(json, "reason"),
             heartbeat = json.optJSONObject("heartbeat")?.let { heartbeatMetaFromJson(it) },
+            stoppedAt = Iso8601.parse(JsonUtil.optString(json, "stopped_at")),
+            network = ConnectivityType.fromWire(JsonUtil.optString(json, "network")),
+            device = json.optJSONObject("device")?.let { deviceFromJson(it) },
+            batteryDetails = batteryDetails,
         )
     }
 
@@ -426,6 +476,13 @@ object DeviceInfoJson {
             .put("hmsAvailable", d.hmsAvailable)
             .put("backend", d.backend.wire)
             .put("packagedProviders", providers)
+            .put("backendFallbackReason", JsonUtil.orNull(d.backendFallbackReason))
+            .put("gmsStatus", JsonUtil.orNull(d.gmsStatus))
+            .put("hmsStatus", JsonUtil.orNull(d.hmsStatus))
+            .put("hmsCoreOutdated", JsonUtil.orNull(d.hmsCoreOutdated))
+            .put("locationAvailableHint", JsonUtil.orNull(d.locationAvailableHint))
+            .put("cpuCores", d.cpuCores)
+            .put("supportedAbis", JSONArray().also { abis -> d.supportedAbis.forEach { abis.put(it) } })
     }
 }
 
@@ -497,6 +554,8 @@ object EventJson {
     const val ENABLEDCHANGE = "enabledchange"
     const val NOTIFICATIONACTION = "notificationaction"
     const val AUTHORIZATION = "authorization"
+    const val LOCATIONERROR = "locationerror"
+    const val STORAGEFULL = "storagefull"
 
     fun name(event: TrackingEvent): String = when (event) {
         is TrackingEvent.Location -> LOCATION
@@ -512,6 +571,8 @@ object EventJson {
         is TrackingEvent.EnabledChange -> ENABLEDCHANGE
         is TrackingEvent.NotificationAction -> NOTIFICATIONACTION
         is TrackingEvent.Authorization -> AUTHORIZATION
+        is TrackingEvent.LocationError -> LOCATIONERROR
+        is TrackingEvent.StorageFull -> STORAGEFULL
     }
 
     fun payload(event: TrackingEvent): JSONObject = when (event) {
@@ -538,7 +599,8 @@ object EventJson {
         is TrackingEvent.Http -> HttpResultJson.toJson(event.result)
         is TrackingEvent.ConnectivityChange -> ConnectivityJson.toJson(event.connectivity)
         is TrackingEvent.PowerSaveChange -> JSONObject().put("isPowerSaveMode", event.isPowerSaveMode)
-        is TrackingEvent.EnabledChange -> JSONObject().put("enabled", event.enabled)
+        is TrackingEvent.EnabledChange ->
+            JSONObject().put("enabled", event.enabled).put("reason", JsonUtil.orNull(event.reason))
         is TrackingEvent.NotificationAction -> JSONObject().put("id", event.id)
         is TrackingEvent.Authorization -> {
             val json = JSONObject().put("success", event.success).put("status", event.status)
@@ -546,5 +608,14 @@ object EventJson {
             JsonUtil.parseObject(event.responseJson)?.let { json.put("response", it) }
             json
         }
+        is TrackingEvent.LocationError -> JSONObject()
+            .put("code", event.code.name)
+            .put("message", event.message)
+            .put("backend", event.backend.wire)
+            .put("retryInMs", JsonUtil.orNull(event.retryInMs))
+        is TrackingEvent.StorageFull -> JSONObject()
+            .put("uuid", event.uuid)
+            .put("event", event.event.wire)
+            .put("diskFreeBytes", JsonUtil.orNull(event.diskFreeBytes))
     }
 }

package/android/src/main/java/com/brickssoft/locationtracking/model/Record.kt

@@ -85,6 +85,11 @@ data class GeofenceHit(val identifier: String, val action: GeofenceAction, val e
  * @property provider event `providerchange` only.
  * @property reason `tracking_start` / `tracking_stop` only.
  * @property heartbeat `heartbeat` only, and optional (round 2): the scheduling metadata of the heartbeat.
+ * @property stoppedAt `tracking_stop` only, when the stop happened before the record could be written (reason
+ *   `user_stopped`: the time the user stopped the app), epoch ms.
+ * @property network the connection type when the record was created (every record; null if unknown).
+ * @property device device readings (heartbeat and `tracking_start` records only).
+ * @property batteryDetails battery temperature, health and power source (heartbeat records only).
  */
 data class Record(
     val uuid: String,
@@ -103,4 +108,8 @@ data class Record(
     val provider: ProviderState? = null,
     val reason: String? = null,
     val heartbeat: HeartbeatMeta? = null,
+    val stoppedAt: Long? = null,
+    val network: ConnectivityType? = null,
+    val device: DeviceSnapshot? = null,
+    val batteryDetails: BatteryDetails? = null,
 )

package/android/src/main/java/com/brickssoft/locationtracking/model/TrackedLocation.kt

@@ -26,13 +26,23 @@ data class TrackedLocation(
     val isMock: Boolean = false,
 ) {
     companion object {
-        /** Converts an Android [android.location.Location], keeping only the fields it actually has. */
+        /**
+         * The accuracy of a fix that has none (`Location.hasAccuracy()` false; some platform providers): 1,000 km,
+         * so the accuracy filters (`trackingAccuracyThreshold`, default 100 m) reject it. Before, it was stored as
+         * 0 m, which passes every accuracy filter (recommendation 12).
+         */
+        const val UNKNOWN_ACCURACY_M = 1_000_000f
+
+        /**
+         * Converts an Android [android.location.Location], keeping only the fields it actually has. A missing
+         * horizontal accuracy becomes [UNKNOWN_ACCURACY_M].
+         */
         fun from(l: android.location.Location): TrackedLocation {
             val api26 = Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
             return TrackedLocation(
                 latitude = l.latitude,
                 longitude = l.longitude,
-                accuracy = l.accuracy,
+                accuracy = if (l.hasAccuracy()) l.accuracy else UNKNOWN_ACCURACY_M,
                 altitude = if (l.hasAltitude()) l.altitude else null,
                 altitudeAccuracy = if (api26 && l.hasVerticalAccuracy()) l.verticalAccuracyMeters else null,
                 speed = if (l.hasSpeed()) l.speed else null,

package/android/src/main/java/com/brickssoft/locationtracking/position/DefaultPositionService.kt

@@ -33,7 +33,8 @@ import kotlin.math.min
  *   `maximumAgeMs > 0` it returns the freshest known fix (runtime or backend last location) if it is young
  *   enough. Otherwise it samples a temporary backend request for up to `samples` fixes, stops early on a fix of
  *   [ACCURATE_ENOUGH_M] or better, and keeps the most accurate fix. The timeout bounds the whole call; at the
- *   timeout the best fix so far is returned, or TIMEOUT is thrown if there is none.
+ *   timeout the best fix so far is returned, or TIMEOUT is thrown if there is none. If the backend refuses the request
+ *   (also later, through `LocationListener.onError`), the call rejects at once with that error.
  * - [watchPosition] registers one backend listener per watch id. Each fix becomes a `watch_position` record,
  *   optionally persisted through [recordSink], and is delivered in order from [scope] (see [PositionWatch]).
  *
@@ -162,7 +163,14 @@ class DefaultPositionService(
         if (timeoutMs <= 0) return null
         val collector = SampleCollector(o.samples)
         val fixes = Channel<TrackedLocation>(Channel.UNLIMITED)
-        val listener = LocationListener { batch -> batch.forEach { fixes.trySend(it) } }
+        val listener = object : LocationListener {
+            override fun onLocations(locations: List<TrackedLocation>) = locations.forEach { fixes.trySend(it) }
+
+            // The request failed (recommendation 3c): reject at once with that error instead of TIMEOUT.
+            override fun onError(error: TrackingException) {
+                fixes.close(error)
+            }
+        }
         val spec = LocationRequestSpec(o.desiredAccuracy, SAMPLE_INTERVAL_MS, SAMPLE_FASTEST_INTERVAL_MS, 0f)
         val requestedAt = clock.elapsedRealtime()
         try {

package/android/src/main/java/com/brickssoft/locationtracking/position/PositionWatch.kt

@@ -38,7 +38,11 @@ internal class PositionWatch(
     /** Guards [started], [stopped], [registered] and every [callback] invocation. */
     private val lock = Any()
     private val fixes = Channel<TrackedLocation>(BUFFER, BufferOverflow.DROP_OLDEST)
-    private val listener = LocationListener { batch -> batch.forEach { fixes.trySend(it) } }
+    private val listener = object : LocationListener {
+        override fun onLocations(locations: List<TrackedLocation>) = locations.forEach { fixes.trySend(it) }
+
+        override fun onError(error: TrackingException) = onRequestFailed(error)
+    }
 
     @Volatile
     private var stopped = false
@@ -69,6 +73,25 @@ internal class PositionWatch(
         }
     }
 
+    /**
+     * The backend refused the request after [start] returned (recommendation 3): [callback] gets the error once and the
+     * watch ends (the backend no longer has the listener).
+     */
+    private fun onRequestFailed(error: TrackingException) {
+        synchronized(lock) {
+            if (stopped) return
+            try {
+                callback(null, error)
+            } catch (e: Exception) {
+                Logger.e(DefaultPositionService.TAG, "watch $id callback failed", e)
+            }
+            stopped = true
+            registered = false
+        }
+        fixes.close()
+        Logger.w(DefaultPositionService.TAG, "watch $id ended: ${error.code} ${error.message}")
+    }
+
     /** Removes the backend listener and ends deliveries. */
     fun stop() {
         val wasRegistered = synchronized(lock) {

package/android/src/main/java/com/brickssoft/locationtracking/processing/DefaultRecordFactory.kt

@@ -6,8 +6,11 @@ import com.brickssoft.locationtracking.core.ErrorCode
 import com.brickssoft.locationtracking.core.Iso8601
 import com.brickssoft.locationtracking.core.Logger
 import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.device.DeviceDetails
 import com.brickssoft.locationtracking.device.DeviceMonitor
 import com.brickssoft.locationtracking.model.BatterySnapshot
+import com.brickssoft.locationtracking.model.ConnectivityType
+import com.brickssoft.locationtracking.model.DeviceSnapshot
 import com.brickssoft.locationtracking.model.GeofenceHit
 import com.brickssoft.locationtracking.model.JsonUtil
 import com.brickssoft.locationtracking.model.ProviderKind
@@ -20,16 +23,19 @@ import org.json.JSONObject
 import java.util.UUID
 
 /**
- * Builds records: uuid v4, clock and boot metadata, runtime state (isMoving, odometer, activity), battery and
- * the current provider state (unless the caller passes one, as `providerchange` does) from [device], backend from
- * [providers], and `extras` = `persistence.extras` merged with the per-call extras (per-call keys win; null when
- * both are empty).
+ * Builds records: uuid v4, clock and boot metadata, runtime state (isMoving, odometer, activity), battery, the
+ * connection type and the current provider state (unless the caller passes one, as `providerchange` does) from
+ * [device], backend from [providers], and `extras` = `persistence.extras` merged with the per-call extras (per-call keys
+ * win; null when both are empty). Every record gets `device.device_id` from [details]; heartbeat records also get its
+ * device and battery readings, and `tracking_start` records the phone's model, Android version and memory.
  */
 class DefaultRecordFactory(
     private val configStore: ConfigStore,
     private val device: DeviceMonitor,
     private val providers: ProviderFactory,
     private val clock: Clock,
+    /** The device id of every record, and readings for heartbeat and `tracking_start` records (parts d1 to d7). */
+    private val details: DeviceDetails = DeviceDetails.NONE,
 ) : RecordFactory {
     override fun create(
         event: RecordEvent,
@@ -56,16 +62,30 @@ class DefaultRecordFactory(
             geofence = geofence,
             provider = provider ?: providerState(),
             reason = reason,
+            network = network(),
+            device = when (event) {
+                RecordEvent.HEARTBEAT -> details.forHeartbeat()
+                RecordEvent.TRACKING_START -> details.forTrackingStart()
+                else -> DeviceSnapshot()
+            }.copy(deviceId = details.deviceId()).takeUnless { it.isEmpty },
+            batteryDetails = if (event == RecordEvent.HEARTBEAT) details.batteryDetails() else null,
         )
     }
 
+    private fun network(): ConnectivityType? = try {
+        device.connectivity().type
+    } catch (e: Exception) {
+        Logger.w(TAG, "connectivity unavailable", e)
+        null
+    }
+
     /**
-     * Parses a JS `InsertLocationInput`: `{coords:{latitude, longitude, accuracy?, altitude?, ...}, timestamp?,
-     * event?, is_moving?, extras?}`. `accuracy` defaults to 0; negative optional accuracies, speed and heading
-     * (the "unknown" sentinel of some platforms) become null.
+     * Parses a JS `InsertLocationInput`: `{coords:{latitude, longitude, accuracy, altitude?, ...}, timestamp?,
+     * event?, is_moving?, extras?}`. Negative optional accuracies, speed and heading (the "unknown" sentinel of some
+     * platforms) become null.
      *
      * @throws TrackingException INVALID_ARGUMENT if coords, latitude or longitude are missing or invalid, if
-     *   accuracy is negative, or if `timestamp`, `event`, `is_moving` or `extras` are given but invalid.
+     *   accuracy is missing or not greater than 0, or if `timestamp`, `event`, `is_moving` or `extras` are given but invalid.
      */
     override fun fromExternal(input: JSONObject): Record {
         val coords = input.optJSONObject("coords") ?: invalid("location.coords is required")
@@ -90,8 +110,9 @@ class DefaultRecordFactory(
         } else {
             JsonUtil.optBoolean(input, "is_moving") ?: invalid("is_moving must be a boolean")
         }
-        val accuracy = JsonUtil.optFloat(coords, "accuracy") ?: 0f
-        if (accuracy < 0) invalid("coords.accuracy must be >= 0")
+        // Round 3: no default; an accuracy of 0 would read as a perfect fix.
+        val accuracy = JsonUtil.optFloat(coords, "accuracy") ?: invalid("coords.accuracy is required")
+        if (!(accuracy > 0)) invalid("coords.accuracy must be > 0")
         val extras = if (input.isNull("extras")) {
             null
         } else {

package/android/src/main/java/com/brickssoft/locationtracking/provider/Backends.kt

@@ -1,5 +1,6 @@
 package com.brickssoft.locationtracking.provider
 
+import com.brickssoft.locationtracking.core.TrackingException
 import com.brickssoft.locationtracking.model.ActivitySample
 import com.brickssoft.locationtracking.model.DesiredAccuracy
 import com.brickssoft.locationtracking.model.GeofenceAction
@@ -17,6 +18,13 @@ data class LocationRequestSpec(
 /** Receives batches of fixes, on any thread. */
 fun interface LocationListener {
     fun onLocations(locations: List<TrackedLocation>)
+
+    /**
+     * The request made with this listener failed, synchronously or later (recommendation 3): for example a missing
+     * permission, Google Play services or HMS Core refusing the request, or no usable platform provider. The listener is
+     * no longer registered. Called at most once per request, on any thread.
+     */
+    fun onError(error: TrackingException) = Unit
 }
 
 /** Location updates and one-shot fixes from one backend. */
@@ -25,8 +33,8 @@ interface LocationBackend {
 
     /**
      * Supports multiple listeners; requesting again with the same listener replaces its request. A `distanceFilterM`
-     * of 0 means no distance filter (the engine applies its own elastic filter). Never throws: failures such as a
-     * missing permission are logged and the listener receives nothing.
+     * of 0 means no distance filter (the engine applies its own elastic filter). Never throws: a failure, also one the
+     * OS reports later, is logged and reported to [LocationListener.onError] (see [LocationSubscriptions]).
      */
     fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener)
 
@@ -35,8 +43,18 @@ interface LocationBackend {
     /** The OS's cached last location. Implementations may throw `TrackingException(PERMISSION_DENIED)`; callers catch. */
     suspend fun getLastLocation(): TrackedLocation?
 
-    /** Returns null on timeout. @throws com.brickssoft.locationtracking.core.TrackingException PERMISSION_DENIED */
+    /**
+     * Returns null on timeout. A request the OS refuses throws at once (recommendation 3c), not after the timeout.
+     * @throws com.brickssoft.locationtracking.core.TrackingException PERMISSION_DENIED, or the backend's mapping of
+     *   the OS error (for example UNAVAILABLE).
+     */
     suspend fun getCurrentLocation(accuracy: DesiredAccuracy, timeoutMs: Long): TrackedLocation?
+
+    /**
+     * The last `LocationAvailability` that GMS or HMS reported for this backend's requests, or null (none yet, or the
+     * platform backend). A hint only: Google documents that it can be wrong in both directions.
+     */
+    val availabilityHint: Boolean? get() = null
 }
 
 /** Activity recognition. Samples are delivered through a PendingIntent receiver to [ActivitySink]. */
@@ -91,6 +109,12 @@ interface ProviderBundle {
     /** True if the SDK is packaged and usable on this device (e.g. `GoogleApiAvailability` SUCCESS). */
     fun isAvailable(): Boolean
 
+    /** The raw availability result code of the last [isAvailable] (0 = SUCCESS), or null if unknown. */
+    fun availabilityStatus(): Int? = null
+
+    /** A diagnostic about the installed SDK service that does not change the choice (HMS: an old HMS Core), or null. */
+    fun versionDiagnostic(): String? = null
+
     fun location(): LocationBackend
 
     fun activity(): ActivityBackend
@@ -112,8 +136,29 @@ interface ProviderFactory {
 
     /** Re-evaluates the selection (e.g. after setConfig). Returns true if [kind] changed. */
     fun reselect(): Boolean
+
+    /**
+     * What [reselect] would select now, without changing the selection. With `locationProvider: 'auto'` the engine
+     * compares it with [kind] on provider changes and heartbeats, and switches when it is better (recommendation 15).
+     */
+    fun bestAvailable(): ProviderKind = kind
+
+    /** Why the current backend was selected and the raw availability codes (recommendation 15); diagnostic only. */
+    fun selectionInfo(): ProviderSelectionInfo = ProviderSelectionInfo(fallbackReason = null, gmsStatus = null, hmsStatus = null)
 }
 
+/**
+ * Diagnostics of the provider choice: [fallbackReason] says why a better backend was not used (null when the preferred
+ * one was), [gmsStatus] / [hmsStatus] are the raw `GoogleApiAvailability` / `HuaweiApiAvailability` result codes (null
+ * when that SDK is not packaged), and [hmsCoreOutdated] is true when HMS Core is older than 6.3.0.301.
+ */
+data class ProviderSelectionInfo(
+    val fallbackReason: String?,
+    val gmsStatus: Int?,
+    val hmsStatus: Int?,
+    val hmsCoreOutdated: Boolean? = null,
+)
+
 /** Implemented by the TrackingEngine. */
 interface ActivitySink {
     suspend fun onActivitySamples(samples: List<ActivitySample>)

package/android/src/main/java/com/brickssoft/locationtracking/provider/DefaultProviderFactory.kt

@@ -43,6 +43,9 @@ class DefaultProviderFactory(
     /** Created bundles; a null value means the bundle could not be loaded. Guarded by [lock]. */
     private val bundles = HashMap<ProviderKind, ProviderBundle?>()
 
+    /** Bundles whose [ProviderBundle.versionDiagnostic] is logged once, when they are created. Guarded by [lock]. */
+    private val bundleVersionWarnings = HashSet<ProviderKind>()
+
     override val kind: ProviderKind get() = current().kind
 
     override fun location(): LocationBackend = current().bundle.location()
@@ -56,6 +59,56 @@ class DefaultProviderFactory(
         return isUsable(bundle)
     }
 
+    override fun bestAvailable(): ProviderKind = synchronized(lock) {
+        if (configStore.config.value.locationProvider != LocationProviderSetting.AUTO) return@synchronized kind
+        when {
+            availableLocked(ProviderKind.GMS) -> ProviderKind.GMS
+            availableLocked(ProviderKind.HMS) -> ProviderKind.HMS
+            else -> ProviderKind.ANDROID
+        }
+    }
+
+    /**
+     * Why the current backend was selected (recommendation 15): for each better backend that was not used, its reason
+     * (not listed, SDK not packaged, receivers removed, or the availability status code); null when the preferred
+     * backend is used. The status codes are those of the last availability checks.
+     */
+    override fun selectionInfo(): ProviderSelectionInfo = synchronized(lock) {
+        val setting = configStore.config.value.locationProvider
+        val current = current().kind
+        val preferred = when (setting) {
+            LocationProviderSetting.AUTO -> listOf(ProviderKind.GMS, ProviderKind.HMS)
+            LocationProviderSetting.GMS -> listOf(ProviderKind.GMS)
+            LocationProviderSetting.HMS -> listOf(ProviderKind.HMS)
+            LocationProviderSetting.ANDROID -> emptyList()
+        }
+        val skipped = preferred.takeWhile { it != current }.map { kind -> "${kind.wire}: ${skipReasonLocked(kind)}" }
+        val hms = bundles[ProviderKind.HMS]
+        ProviderSelectionInfo(
+            fallbackReason = skipped.takeIf { it.isNotEmpty() }?.joinToString("; "),
+            gmsStatus = bundles[ProviderKind.GMS]?.availabilityStatus(),
+            hmsStatus = hms?.availabilityStatus(),
+            hmsCoreOutdated = hms?.let { guard("HMS Core version check") { it.versionDiagnostic() } != null },
+        )
+    }
+
+    private fun skipReasonLocked(kind: ProviderKind): String {
+        when (packaging.status(kind)) {
+            ProviderPackaging.Status.NOT_LISTED -> return "not listed in ${ProviderPackaging.PROVIDERS_META_DATA}"
+            ProviderPackaging.Status.SDK_MISSING -> return "SDK not packaged"
+            ProviderPackaging.Status.RECEIVERS_REMOVED -> return "receivers not in the manifest"
+            ProviderPackaging.Status.PACKAGED -> Unit
+        }
+        val bundle = bundleLocked(kind) ?: return "backend could not be loaded"
+        val available = isUsable(bundle)
+        val status = bundle.availabilityStatus()
+        return when {
+            available -> "available, not selected"
+            status != null -> "unavailable (status $status)"
+            else -> "unavailable"
+        }
+    }
+
     override fun reselect(): Boolean = synchronized(lock) {
         val previous = selection
         val next = selectLocked()
@@ -106,6 +159,10 @@ class DefaultProviderFactory(
             ProviderPackaging.Status.SDK_MISSING -> "SDK is not packaged"
             ProviderPackaging.Status.RECEIVERS_REMOVED -> "SDK is present but its receivers are not in the manifest"
         }
+        if (reason == null && kind == ProviderKind.HMS) {
+            // Diagnostic only (recommendation 15): HMS is used whatever the HMS Core version.
+            bundleVersionWarnings += kind
+        }
         if (reason != null) {
             // Listed in the app's PROVIDERS meta-data but unusable is a setup error; otherwise it is expected.
             if (packaging.listedExplicitly(kind)) {
@@ -117,6 +174,9 @@ class DefaultProviderFactory(
         }
         val name = ProviderBundles.bundleClassName(kind)
         val bundle = guard("create $name") { createBundle(name) }
+        if (bundle != null && kind in bundleVersionWarnings) {
+            guard("${kind.wire} version check") { bundle.versionDiagnostic() }?.let { Logger.w(TAG, it) }
+        }
         if (bundle == null && kind == ProviderKind.ANDROID) {
             // The last resort must always exist; it lives in this module, so it can be constructed directly.
             Logger.e(TAG, "reflective creation of the android bundle failed; constructing it directly")