@tokamakdev/plugin-location 0.1.0-beta.102 → 0.1.0-beta.103

package/README.md

@@ -1,8 +1,8 @@
 # @tokamakdev/plugin-location
 
-Location for Tokamak applications and the web.
-
-Add it to your project's dependencies:
+Location for tokamak applications and the web: positions on request, and
+updates, regions, significant changes and visits that reach the app's Worker
+off screen.
 
 ```sh
 npm install @tokamakdev/plugin-location
@@ -12,32 +12,212 @@ npm install @tokamakdev/plugin-location
 import { location } from "@tokamakdev/plugin-location";
 
 const position = await location.getCurrentPosition();
+const stop = location.watchPosition((next) => console.log(next.coords), console.error);
+
+await location.requestPermission({ background: true });
+await location.startUpdates({ activity: "fitness", accuracy: "high", distance: 10 });
+await location.addRegion({ id: "home", latitude: 51.5, longitude: -0.12, radius: 150 });
+```
+
+```ts
+// src/tokamak.ts
+import { onLocationUpdate, onRegionTransition } from "@tokamakdev/plugin-location/events";
 
-const stop = location.watchPosition(
-  (next) => console.log(next.coords.latitude, next.coords.longitude),
-  console.error,
-);
+onLocationUpdate(async ({ positions }, env) => {
+  await fetch("https://example.com/track", { method: "POST", body: JSON.stringify(positions) });
+});
+onRegionTransition(({ id, transition }) => console.log(id, transition));
 ```
 
+## Positions
+
 `getCurrentPosition` takes the Geolocation API's `maximumAge` and `timeout`
 options. It resolves with a recent position no older than `maximumAge`
 milliseconds, 0 by default, or takes a new one, and rejects with
 `TimeoutError` when none arrives within `timeout` milliseconds, unlimited by
 default. The timeout starts once the user allows location.
 
-## Off screen
+`watchPosition(next, error)` calls `next` with each new position until the
+function it returns is called.
 
-The plugin asks for location while the app is in use only. While the app is
-off screen on iOS or Android, as when Worker code runs in the background, a
-call that would ask the user for permission rejects with `NeedsUIError`. With
-permission granted, the platforms stop locating an app that is off screen
-without background location permission, which the plugin does not request, so
+Both ask for in-use permission when the user has not answered. Off screen
+without background permission, the platforms stop locating the app, so
 `getCurrentPosition` rejects with `NotAllowedError` there. iOS still locates
-the app for a few seconds after it leaves the screen.
+the app for a few seconds after it leaves the screen. With approximate
+permission, Android gives an app a new position at most every 10 minutes, so
+`getCurrentPosition` can wait that long.
+
+## Permission
+
+`permission()` reports the app's permission without asking:
+
+- `inUse` and `background`, each `"granted"`, `"denied"` or `"prompt"`.
+  `background` is `"denied"` unless the `background` build setting declares
+  it. macOS has no separate background permission, so `background` equals
+  `inUse` there.
+- `precision`: `"precise"` or `"approximate"`, what the app gets or would get
+  once allowed.
+
+`requestPermission(options)` asks for in-use permission where the user has not
+answered, and for what `options` names, then resolves with the permission:
+
+- `background: true` asks for background permission.
+  - **iOS** shows the Always prompt once, from When In Use. Asked before the
+    user has answered, it gives provisional Always, which iOS confirms with
+    the user later. Without the `background` build setting it rejects with
+    `NotSupportedError`.
+  - **Android** asks for in-use permission first, as Android grants
+    background permission only after it. From Android 11 the request opens
+    the app's page in Settings, where the user picks "Allow all the time".
+- `precision: "precise"` asks for precise location where the user allowed
+  approximate. Apple platforms grant it temporarily, while the app is in use,
+  for the reason the `accuracy-purposes` build setting gives for `purpose`.
+  `precision: "approximate"` asks Android for approximate location only.
+
+Off screen on iOS and Android, a request that would show a prompt rejects with
+`NeedsUIError`. `openSettings()` opens the app's page in the system settings,
+or Location Services on macOS, where the user changes the permission.
+`servicesEnabled()` reports whether location services are on for the device.
+
+## Build settings
+
+The plugin's declarations come from its build settings, set in the tokamak
+Vite plugin's options, as `--location-<key>`, or as `TOKAMAK_LOCATION_<KEY>`:
+
+```js
+// vite.config.js
+tokamak({
+  location: {
+    background: true,
+    "background-updates": true,
+    "accuracy-purposes": { Directions: "Shows directions from where you are" },
+  },
+});
+```
+
+| Setting | Kind | Declares |
+|---|---|---|
+| `background` | boolean | Background permission: iOS's Always reason, Android's `ACCESS_BACKGROUND_LOCATION`. |
+| `background-updates` | boolean | Updates off screen: iOS's `location` background mode, Android's location foreground service and its permissions. |
+| `precision` | `precise` or `approximate` | `approximate` declares approximate location only: iOS's `NSLocationDefaultAccuracyReduced`, and Android without `ACCESS_FINE_LOCATION`. macOS has no such declaration. |
+| `when-in-use-description` | string | Apple: the in-use prompt's reason, and macOS's only reason. |
+| `always-description` | string | iOS: the Always prompt's reason. Needs `background`. |
+| `accuracy-purposes` | map of string | Apple: the reasons for temporary precise location, by purpose key. |
+
+Without a description the plugin uses a generic English reason. Declare only
+what the app uses: App Review rejects background modes an app has no feature
+for, and Google Play reviews background location and foreground service types
+with a declaration and a video.
+
+## Worker events
+
+The Worker's listeners, from `@tokamakdev/plugin-location/events`, run whether
+or not a page is loaded, including when the system launches the app for an
+event:
+
+| Event | Receives |
+|---|---|
+| `onLocationUpdate` | `{ positions, stationary? }` from updates and significant changes. |
+| `onRegionTransition` | `{ id, transition, timestamp }`, where `transition` is `"enter"` or `"exit"`. |
+| `onVisit` | Apple only: `{ latitude, longitude, accuracy, arrival, departure }`, times in milliseconds or null when unknown. |
+| `onLocationError` | `{ name, message, id? }` when a background service fails, with the region's `id` when it concerns one. |
+
+`positions` holds the positions that arrived while the Worker handled the
+previous update, oldest first, so a slow Worker never builds a queue. Apple's
+`stationary`, from iOS 18 and macOS 15, is true on the last update before
+updates pause while the device is still.
+
+The plugin's `onLocationUpdate`, `onRegionTransition`, `onVisit` and
+`onLocationError` methods receive the same events while the listening page or
+Worker runs, and return the function that removes the listener.
+
+## Updates
+
+`startUpdates(options)` starts continuous updates, replacing any running,
+until `stopUpdates()`. `getUpdates()` resolves with the running updates'
+options, or null. Updates need in-use permission, and reject with
+`NotAllowedError` without it. The plugin keeps them across launches and
+restarts.
+
+**Apple** uses `CLLocationUpdate.liveUpdates`.
+
+- `activity` is the live configuration: `"default"`, `"automotiveNavigation"`,
+  `"otherNavigation"`, `"fitness"`, `"airborne"`, or `"maritime"` (iOS 27 and
+  macOS 27). It tunes when updates pause and how coordinates follow roads.
+- Updates pause while the device is still and resume when it moves.
+- If iOS ends the app while updates run, it launches the app for the next
+  update, and the plugin resumes them.
+- Off screen, updates need the `background-updates` build setting, which
+  shows the location indicator, or Always permission. `startUpdates` rejects
+  with `NeedsUIError` off screen on iOS.
+- From iOS 18, failures such as denied permission or lost location reach
+  `onLocationError` once each.
+- `getCurrentPosition` and `watchPosition` can change the coordinates updates
+  deliver while they run.
+
+**Android** uses `LocationManager` with a `PendingIntent`, which starts the
+app's process for each update.
+
+- `accuracy` is `"high"` (default), `"balanced"` or `"low"`; `distance` the
+  metres between updates, 0 by default; `interval` the milliseconds between
+  them, 10 seconds by default.
+- Off screen, updates need background permission and arrive a few times an
+  hour, unless they run in a foreground service.
+- `foregroundService: { title, body, channel }` runs updates in a foreground
+  service, with that notification in a channel of that name, at the requested
+  rate off screen. It needs the `background-updates` build setting, and
+  rejects with `NotSupportedError` without it. Off screen it needs background
+  permission, and Android starts the service only within 10 seconds of an
+  update; otherwise it rejects with `NeedsUIError`. A region transition does
+  not allow the start.
+- The plugin requests updates again after a restart, an app update and a
+  force stop, and starts the service again on screen, or after a restart or
+  update with background permission. Android restarts a service it ends for
+  memory.
+
+## Regions
+
+`addRegion({ id, latitude, longitude, radius, onEntry, onExit })` monitors a
+circular region of `radius` metres, replacing one with the same `id`, until
+`removeRegion(id)`. `onEntry` and `onExit` are true by default. Entries and
+exits reach `onRegionTransition`, including when the system launches the app
+for one. A region starts outside, so a device already inside reports an
+entry. `getRegions()` resolves with the regions, each with its `state` on
+Apple platforms: `"inside"`, `"outside"` or `"unknown"`.
+
+Regions need precise location, and reject with `NotAllowedError` without it,
+and background permission off screen.
+
+- **Apple** uses `CLMonitor`, which monitors up to 20 regions; `addRegion`
+  rejects with `QuotaExceededError` beyond them. iOS relaunches the app for a
+  transition, even after the user quits it. macOS monitors only while the app
+  runs.
+- **Android** uses proximity alerts, which the system evaluates about every 30
+  minutes or less often, so a transition can arrive that long after it
+  happens. Adding a region again, as the plugin does after a restart, reports
+  an entry again for a device inside.
+
+## Significant changes and visits
+
+On Apple platforms, `setup(config)` starts what runs at every launch:
+`significantChanges` delivers significant changes of location to
+`onLocationUpdate`, and `visits` delivers visits to `onVisit`. Call it from
+`onStart` in `src/tokamak.ts`. The configuration replaces the previous one,
+which the plugin keeps and applies again at each launch; an invalid one
+rejects with `TypeError` and changes nothing. With Always permission, the
+system relaunches the app for both. Android ignores `setup`'s keys.
 
 ## Platforms
 
-The web implementation uses `navigator.geolocation`. Native Tokamak builds use
-Core Location on Apple platforms, `LocationManager` on Android, and WebView2's
-location implementation on Windows. Calling the API on a platform without
-location support throws `NotSupportedError`.
+The web uses `navigator.geolocation`. `permission()` reports `inUse` from the
+Permissions API, and the other additions reject with `NotSupportedError`,
+while the listener methods receive nothing. Windows uses WebView2's location
+for `getCurrentPosition` and `watchPosition`.
+
+## Errors
+
+Rejections and `onLocationError` events are `DOMException` names:
+`NotAllowedError` (no permission, or none for the background),
+`NotReadableError` (location unavailable, or services off), `NeedsUIError` (a
+prompt or a start off screen), `NotSupportedError`, `QuotaExceededError`,
+`TimeoutError` and `TypeError`.

package/android/LocationEvents.kt

@@ -0,0 +1,82 @@
+package com.tokamak.plugins.location
+
+import android.util.Log
+import com.tokamak.runtime.TokamakHost
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** How long the Worker's listeners have for an event, within the time Android gives a broadcast. */
+private const val EVENT_DEADLINE_MILLIS = 8_000L
+
+/** The listener methods, which receive the Worker's events. */
+private val LISTENERS = setOf("onLocationUpdate", "onRegionTransition", "onVisit", "onLocationError")
+
+/** Delivers the plugin's events to the Worker's listeners and the page's. Use it on the main thread. */
+internal class LocationEvents(private val host: TokamakHost) {
+    private val listeners = mutableMapOf<String, MutableMap<Int, TokamakPluginReply>>()
+    private var nextListener = 0
+
+    /** Positions that arrived while the Worker handled the previous update, and the broadcasts to finish once it has them. */
+    private val positions = mutableListOf<JSONObject>()
+    private val finishes = mutableListOf<() -> Unit>()
+    private var updating = false
+
+    /** Adds a page's or Worker's listener of [method], returning its removal, or null for another method. */
+    fun listen(method: String, reply: TokamakPluginReply): (() -> Unit)? {
+        if (method !in LISTENERS) return null
+        val key = nextListener++
+        listeners.getOrPut(method, ::mutableMapOf)[key] = reply
+        return { listeners[method]?.remove(key) }
+    }
+
+    /**
+     * Delivers [received] positions, then calls [finish]. Positions that arrive while the Worker
+     * handles an update reach it together as the next.
+     */
+    fun update(received: List<JSONObject>, finish: () -> Unit) {
+        positions += received
+        finishes += finish
+        if (!updating) sendUpdate()
+    }
+
+    fun transition(id: String, entered: Boolean, finish: () -> Unit) {
+        val event =
+            JSONObject()
+                .put("id", id)
+                .put("transition", if (entered) "enter" else "exit")
+                .put("timestamp", System.currentTimeMillis())
+        send("onRegionTransition", "region", event, finish)
+    }
+
+    /** Reports a background service's failure, then calls [finish]. */
+    fun fail(error: TokamakPluginError, finish: () -> Unit = {}) {
+        val event = JSONObject().put("name", error.errorName).put("message", error.message)
+        send("onLocationError", "error", event, finish)
+    }
+
+    /** Sends the waiting positions as one update, then the positions that arrive meanwhile as the next. */
+    private fun sendUpdate() {
+        updating = positions.isNotEmpty()
+        if (!updating) return
+        val event = JSONObject().put("positions", JSONArray(positions.toList()))
+        val delivered = finishes.toList()
+        positions.clear()
+        finishes.clear()
+        send("onLocationUpdate", "update", event) {
+            delivered.forEach { it() }
+            sendUpdate()
+        }
+    }
+
+    /** Delivers [event] to the page's [method] listeners and the Worker's [name] listeners, then calls [finish]. */
+    private fun send(method: String, name: String, event: JSONObject, finish: () -> Unit) {
+        listeners[method].orEmpty().values.toList().forEach { it(Result.success(event)) }
+        Thread {
+            runCatching { host.emit(name, event.toString(), EVENT_DEADLINE_MILLIS) }
+                .onFailure { Log.w("tokamak", "location $name failed: ${it.message}") }
+            host.context.mainExecutor.execute(finish)
+        }.start()
+    }
+}

package/android/LocationPlugin.kt

@@ -1,20 +1,29 @@
 package com.tokamak.plugins.location
 
 import android.Manifest
+import android.app.ForegroundServiceStartNotAllowedException
+import android.content.ComponentName
 import android.content.Context
+import android.content.Intent
 import android.content.pm.PackageManager
 import android.location.Location
 import android.location.LocationListener
 import android.location.LocationManager
+import android.net.Uri
 import android.os.Bundle
 import android.os.CancellationSignal
 import android.os.Handler
 import android.os.Looper
 import android.os.SystemClock
+import android.provider.Settings
 import com.tokamak.runtime.TokamakHost
 import com.tokamak.runtime.TokamakPlugin
 import com.tokamak.runtime.TokamakPluginError
 import com.tokamak.runtime.TokamakPluginReply
+import com.tokamak.runtime.optionalString
+import com.tokamak.runtime.requireObject
+import com.tokamak.runtime.requireString
+import org.json.JSONArray
 import org.json.JSONObject
 
 class TokamakLocationPlugin(
@@ -27,14 +36,62 @@ class TokamakLocationPlugin(
         context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
     private val handler = Handler(Looper.getMainLooper())
 
+    /** The permissions the app's manifest requests. */
+    private val declared: Set<String> by lazy {
+        context.packageManager
+            .getPackageInfo(context.packageName, PackageManager.GET_PERMISSIONS)
+            .requestedPermissions
+            .orEmpty()
+            .toSet()
+    }
+
+    /** Foreground location permissions, which the `precision` build setting declares. */
+    private val foreground: Set<String> by lazy { setOf(COARSE, FINE).filter(declared::contains).toSet() }
+
+    private val updates = LocationUpdates(context)
+    private val regions = LocationRegions(context)
+    private val events = LocationEvents(host)
+
+    /** Whether the app's manifest declares the foreground service, as the `background-updates` build setting does. */
+    private val declaresService: Boolean by lazy {
+        runCatching { context.packageManager.getServiceInfo(ComponentName(context, TokamakLocationService::class.java), 0) }
+            .isSuccess
+    }
+
+    init {
+        restore(updatesRemoved = false)
+    }
+
+    /** Starts the updates' foreground service again once the app is on screen. */
+    override fun onIntent(intent: Intent) {
+        if (host.isInForeground) updates.startService()
+    }
+
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
-        if (method != "getCurrentPosition") {
-            super.call(method, arguments, reply)
-            return
-        }
-        val options = arguments as? JSONObject
-        withPermission { granted ->
-            if (granted) currentPosition(options, reply) else reply(permissionDenied())
+        when (method) {
+            // Significant changes and visits, setup's keys, are Apple's.
+            "setup" -> reply(Result.success(null))
+            "getCurrentPosition" ->
+                withPermission { granted ->
+                    if (granted) currentPosition(arguments as? JSONObject, reply) else reply(Result.failure(permissionDenied()))
+                }
+            "permission" -> reply(Result.success(permission()))
+            "requestPermission" -> requestPermission(requireObject(arguments), reply)
+            "servicesEnabled" -> reply(Result.success(manager.isLocationEnabled))
+            "openSettings" -> openSettings(reply)
+            "startUpdates" -> startUpdates(requireObject(arguments), reply)
+            "stopUpdates" -> {
+                updates.stop()
+                reply(Result.success(null))
+            }
+            "getUpdates" -> reply(Result.success(updates.options))
+            "addRegion" -> addRegion(requireObject(arguments), reply)
+            "getRegions" -> reply(Result.success(JSONArray(regions.all())))
+            "removeRegion" -> {
+                regions.remove(requireObject(arguments).requireString("id"))
+                reply(Result.success(null))
+            }
+            else -> super.call(method, arguments, reply)
         }
     }
 
@@ -43,12 +100,13 @@ class TokamakLocationPlugin(
         arguments: Any?,
         reply: TokamakPluginReply,
     ): () -> Unit {
+        events.listen(method, reply)?.let { return it }
         if (method != "watchPosition") return super.subscribe(method, arguments, reply)
         var cancelled = false
         var stop = {}
         withPermission { granted ->
             if (!granted) {
-                reply(permissionDenied())
+                reply(Result.failure(permissionDenied()))
             } else if (!cancelled) {
                 stop = watchPosition(reply)
             }
@@ -64,11 +122,126 @@ class TokamakLocationPlugin(
      * Throws `NeedsUIError` when asking would show UI while the app is in the background.
      */
     private fun withPermission(action: (Boolean) -> Unit) {
-        if (PERMISSIONS.any { context.checkSelfPermission(it) == PackageManager.PERMISSION_GRANTED }) {
+        if (hasForegroundPermission()) {
             action(true)
             return
         }
-        host.requestPermissions(PERMISSIONS) { granted -> action(granted.containsValue(true)) }
+        host.requestPermissions(foreground) { granted -> action(granted.containsValue(true)) }
+    }
+
+    private fun granted(permission: String): Boolean =
+        context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+
+    private fun hasForegroundPermission(): Boolean = granted(FINE) || granted(COARSE)
+
+    /** The app's in-use and background permission, and the precision it gets, or would get once allowed. */
+    private fun permission(): JSONObject {
+        val inUse = if (hasForegroundPermission()) "granted" else state(COARSE)
+        val background = if (BACKGROUND in declared) state(BACKGROUND) else "denied"
+        val precise = granted(FINE) || (!granted(COARSE) && FINE in declared)
+        return JSONObject()
+            .put("inUse", inUse)
+            .put("background", background)
+            .put("precision", if (precise) "precise" else "approximate")
+    }
+
+    private fun state(permission: String): String =
+        when {
+            granted(permission) -> "granted"
+            host.wouldPrompt(permission) -> "prompt"
+            else -> "denied"
+        }
+
+    /**
+     * Asks for foreground permission, then for background permission when [options] ask for it, as
+     * Android grants background permission only to an app with foreground permission.
+     */
+    private fun requestPermission(options: JSONObject, reply: TokamakPluginReply) {
+        val background = options.optBoolean("background")
+        if (background && BACKGROUND !in declared) {
+            throw TokamakPluginError.notSupported("Background location needs the location plugin's background build setting")
+        }
+        val asked = if (options.optionalString("precision") == "approximate") setOf(COARSE) else foreground
+        host.requestPermissions(asked) { granted ->
+            if (!background || !granted.containsValue(true)) return@requestPermissions reply(Result.success(permission()))
+            runCatching { host.requestPermissions(setOf(BACKGROUND)) { reply(Result.success(permission())) } }
+                .onFailure { reply(Result.failure(it)) }
+        }
+    }
+
+    private fun requirePermission() {
+        if (!hasForegroundPermission()) throw TokamakPluginError("NotAllowedError", "Location permission has not been granted")
+    }
+
+    private fun startUpdates(options: JSONObject, reply: TokamakPluginReply) {
+        requirePermission()
+        if (options.has("foregroundService")) requireService()
+        runCatching { updates.start(options) }
+            .onSuccess { reply(Result.success(null)) }
+            .onFailure { reply(Result.failure(locationError(it))) }
+    }
+
+    /**
+     * Throws unless the app declares the foreground service and may start it now: Android 14 and
+     * later allow a location foreground service off screen only with background permission.
+     */
+    private fun requireService() {
+        if (!declaresService) {
+            throw TokamakPluginError.notSupported("The foreground service needs the location plugin's background-updates build setting")
+        }
+        if (!host.isInForeground && !granted(BACKGROUND)) throw TokamakPluginError.needsUI()
+    }
+
+    /** Monitors a region, which needs precise location. */
+    private fun addRegion(region: JSONObject, reply: TokamakPluginReply) {
+        if (!granted(FINE)) throw TokamakPluginError("NotAllowedError", "Regions need precise location")
+        runCatching { regions.add(region) }
+            .onSuccess { reply(Result.success(null)) }
+            .onFailure { reply(Result.failure(locationError(it))) }
+    }
+
+    /**
+     * Restores updates and regions, and starts the updates' foreground service on screen, or after a
+     * restart or an update with background permission. Reports a failure to `onLocationError`.
+     */
+    internal fun restore(updatesRemoved: Boolean) {
+        runCatching {
+            updates.restore(updatesRemoved)
+            if (host.isInForeground || (updatesRemoved && granted(BACKGROUND))) updates.startService()
+        }.onFailure { events.fail(locationError(it)) }
+        runCatching { regions.restore() }.onFailure { events.fail(locationError(it)) }
+    }
+
+    /** Delivers the updates or region transition [intent] carries, then calls [finish]. Call it on the main thread. */
+    internal fun receive(intent: Intent, finish: () -> Unit) {
+        if (intent.action == LocationRegions.REGION_ACTION) return transition(intent, finish)
+        if (intent.hasExtra(LocationManager.KEY_PROVIDER_ENABLED)) {
+            if (intent.getBooleanExtra(LocationManager.KEY_PROVIDER_ENABLED, true)) return finish()
+            return events.fail(TokamakPluginError("NotReadableError", "The location provider was turned off"), finish)
+        }
+        val received = locations(intent).map(::position)
+        if (received.isEmpty()) return finish()
+        events.update(received, finish)
+    }
+
+    /** Delivers a region's entry or exit, when the region reports it. */
+    private fun transition(intent: Intent, finish: () -> Unit) {
+        val id = intent.identifier ?: return finish()
+        val entered = intent.getBooleanExtra(LocationManager.KEY_PROXIMITY_ENTERING, false)
+        val region = regions.get(id) ?: return finish()
+        if (!region.optBoolean(if (entered) "onEntry" else "onExit", true)) return finish()
+        events.transition(id, entered, finish)
+    }
+
+    @Suppress("DEPRECATION")
+    private fun locations(intent: Intent): List<Location> =
+        intent.getParcelableArrayExtra(LocationManager.KEY_LOCATIONS)?.filterIsInstance<Location>()
+            ?: listOfNotNull(intent.getParcelableExtra(LocationManager.KEY_LOCATION_CHANGED))
+
+    private fun openSettings(reply: TokamakPluginReply) {
+        val app = Uri.fromParts("package", context.packageName, null)
+        host.requireForegroundActivity().startActivity(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, app))
+        reply(Result.success(null))
     }
 
     /**
@@ -147,29 +320,31 @@ class TokamakLocationPlugin(
         ).firstOrNull(manager::isProviderEnabled)
             ?: manager.getProviders(true).firstOrNull()
 
-    private fun position(location: Location): Map<String, Any?> =
-        mapOf(
-            "coords" to
-                mapOf(
-                    "latitude" to location.latitude,
-                    "longitude" to location.longitude,
-                    "accuracy" to location.accuracy.toDouble(),
-                    "altitude" to location.altitude.takeIf { location.hasAltitude() },
-                    "altitudeAccuracy" to
-                        location.verticalAccuracyMeters.toDouble()
-                            .takeIf { location.hasVerticalAccuracy() },
-                    "heading" to location.bearing.toDouble().takeIf { location.hasBearing() },
-                    "speed" to location.speed.toDouble().takeIf { location.hasSpeed() },
-                ),
-            "timestamp" to location.time,
-        )
-
-    private fun permissionDenied(): Result<Any?> =
-        Result.failure(TokamakPluginError("NotAllowedError", "Location permission was denied"))
+    private fun position(location: Location): JSONObject =
+        JSONObject()
+            .put(
+                "coords",
+                JSONObject()
+                    .put("latitude", location.latitude)
+                    .put("longitude", location.longitude)
+                    .put("accuracy", location.accuracy.toDouble())
+                    .put("altitude", nullable(location.hasAltitude(), location.altitude))
+                    .put(
+                        "altitudeAccuracy",
+                        nullable(location.hasVerticalAccuracy(), location.verticalAccuracyMeters.toDouble()),
+                    )
+                    .put("heading", nullable(location.hasBearing(), location.bearing.toDouble()))
+                    .put("speed", nullable(location.hasSpeed(), location.speed.toDouble())),
+            )
+            .put("timestamp", location.time)
+
+    private fun nullable(available: Boolean, value: Double): Any = if (available) value else JSONObject.NULL
+
+    private fun permissionDenied() = TokamakPluginError("NotAllowedError", "Location permission was denied")
 
     /** Why no fix came: Android gives none in the background without background location permission. */
     private fun missingFix(): Result<Any?> =
-        if (host.isInForeground || context.checkSelfPermission(BACKGROUND) == PackageManager.PERMISSION_GRANTED) {
+        if (host.isInForeground || granted(BACKGROUND)) {
             unavailable("Location is unavailable")
         } else {
             Result.failure(TokamakPluginError("NotAllowedError", "Location permission does not cover the background"))
@@ -178,14 +353,21 @@ class TokamakLocationPlugin(
     private fun unavailable(message: String): Result<Any?> =
         Result.failure(TokamakPluginError("NotReadableError", message))
 
-    private fun locationFailure(error: Throwable): Result<Any?> =
-        if (error is SecurityException) permissionDenied()
-        else unavailable(error.message ?: "Location is unavailable")
+    private fun locationFailure(error: Throwable): Result<Any?> = Result.failure(locationError(error))
+
+    private fun locationError(error: Throwable): TokamakPluginError =
+        when (error) {
+            is SecurityException -> permissionDenied()
+            // Off screen, Android starts a foreground service only in response to some events.
+            is ForegroundServiceStartNotAllowedException -> TokamakPluginError.needsUI()
+            else -> TokamakPluginError("NotReadableError", error.message ?: "Location is unavailable")
+        }
 
     private companion object {
         /** The `timeout` that never expires, as the page sends it. */
         const val UNLIMITED = 0xffffffffL
-        val PERMISSIONS = setOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION)
+        const val FINE = Manifest.permission.ACCESS_FINE_LOCATION
+        const val COARSE = Manifest.permission.ACCESS_COARSE_LOCATION
         const val BACKGROUND = Manifest.permission.ACCESS_BACKGROUND_LOCATION
     }
 }