# Android active navigation decision — #32

Research checked 2026-09-19. Local ticket index confirms draft `09-published.md` is issue #32, covering spec user stories 31–32. Scope: actual-location route progress, turn speech with screen off, start/stop, interruption recovery and explicit off-route status. Automatic rerouting remains #33. The initial #26 baseline used minSdk 26 / targetSdk 35, framework Kotlin and an app-owned WebView, with fine/coarse location but no foreground service. #31 subsequently added a separate trip-recording foreground service; navigation keeps explicit ownership of its own session.

## Recommended execution model

Use one native, non-exported **location foreground service** owning the selected route, location subscription, progress state and TTS. The WebView displays snapshots and sends bounded start/stop/mute commands; it must not own timers, speech, or location tracking required while screen-off. No Google Play Services dependency is necessary: framework `LocationManager`, `TextToSpeech`, `AudioManager`, `NotificationManager` and `Service` cover this slice. This is an implementation recommendation; no device validation is claimed here.

## Permissions and launch

Declare `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_LOCATION`, existing `ACCESS_COARSE_LOCATION` / `ACCESS_FINE_LOCATION`, and `POST_NOTIFICATIONS`. Declare the service `exported="false"` and `foregroundServiceType="location"`. Android 14+ checks location permission and enabled location before promotion. Navigation is an explicitly supported use of the location type; do not label this `dataSync` or `shortService`. Incidental spoken turn guidance does not require inventing a standalone media-playback workload. [Service type contract](https://developer.android.com/develop/background-work/services/fgs/service-types).

Ask for coarse and fine location together on modern Android when the user starts navigation; approximate-only is a valid user choice. For precise turn prompts, OMOX should explain that approximate positions are insufficient, leave map/planning usable and suppress turn speech until sufficiently accurate fixes are available. Do not repeatedly nag after denial; provide a settings action after a permanent denial. Android may restart the app process when precision is downgraded. [Runtime location permission](https://developer.android.com/develop/sensors-and-location/location/permissions/runtime).

Start from the visible activity following the user's Start action, after permissions are granted. Call `startForegroundService()` then promptly `startForeground()` with a real notification, nonzero ID and location type (API 29+ overload; older overload on API 26–28). Catch startup/security failures and return a clear non-running state. Do not defer the actual start until the activity is backgrounded. Modern Android restricts background FGS starts and while-in-use permission access; a successful `checkSelfPermission()` alone does not prove a background start is eligible. Do not request `ACCESS_BACKGROUND_LOCATION` for this user-started session design. [Launch contract](https://developer.android.com/develop/background-work/services/fgs/launch), [background start restrictions](https://developer.android.com/develop/background-work/services/fgs/restrictions-bg-start).

Create a notification channel on API 26+. Show route/guidance status and an explicit Stop action using immutable, app-scoped PendingIntents. Request notifications on API 33+, but denial is **not** a prerequisite failure for FGS: the foreground notification is still required, and the OS presents the service in Task Manager rather than the notification drawer. Keep Stop accessible in the app and explain the missing drawer control. [Notification permission](https://developer.android.com/develop/ui/views/notifications/notification-permission).

## Location without Play Services

Subscribe through `LocationManager.requestLocationUpdates(provider, minTimeMs, minDistanceM, listener, looper)`, available throughout the supported API range. Prefer GPS when enabled; a network provider is optional and must be detected rather than assumed. Handle absent/disabled providers and `SecurityException`; remove every registered listener on session end. Framework fused provider availability varies and is not needed for this implementation. [LocationManager API](https://developer.android.com/reference/android/location/LocationManager).

OMOX policy, to be tested rather than represented as Android guarantees:

- Start with updates around 2 seconds / 5 metres during active navigation, then measure and tune in #37. Callback cadence is a request, not a timing guarantee.
- Reject invalid coordinates and stale/out-of-order fixes using monotonic elapsed-realtime timestamps; inspect accuracy. `getLastKnownLocation` is not a fresh fix.
- Use distance along the selected polyline, local segment projection and bounded forward progress; avoid jumping to a distant branch at a crossing.
- With poor accuracy, disabled GPS or a stale-fix deadline, mark location uncertain and stop issuing location-specific turns. A deadline must fire even when no further callbacks arrive.
- Off-route is its own status, with hysteresis. Do not announce a newly calculated route before #33 exists.
- A foreground location service permits ongoing screen-off access when validly started. This is not a promise of uninterrupted GPS, radio availability or immunity to manufacturer power management. [Android location/background limits](https://developer.android.com/about/versions/oreo/background-location-limits).

## Speech and interruptions

Declare a manifest `queries` intent for `android.intent.action.TTS_SERVICE`. Initialize `TextToSpeech` asynchronously; check initialization and requested language availability, handle missing voice data without crashing, and call `shutdown()` when finished. Use unique utterance IDs and `UtteranceProgressListener`; a successful `speak()` enqueue is not proof of playback. `stop()` clears pending speech on stop, stale GPS or off-route transitions. [TTS API](https://developer.android.com/reference/android/speech/tts/TextToSpeech).

Use `AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE` and `CONTENT_TYPE_SPEECH` for the TTS engine and matching audio-focus request. Request `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` around a prompt via `AudioFocusRequest` (API 26 baseline). On focus loss/transient loss stop speech and suppress stale queued prompts; on recovery compute whether a prompt is still relevant before speaking. Abandon focus on completion/error. Android 15 requires top-app or FGS status to request focus; the active navigation FGS meets that prerequisite. [Audio attributes](https://developer.android.com/reference/android/media/AudioAttributes), [audio focus](https://developer.android.com/media/optimize/audio-focus).

Deduplicate using session ID + route revision + maneuver + threshold, not every GPS callback. Persist consumed prompts across activity recreation and process recovery. Differentiate an interrupted prompt from one completed, while applying cooldown/relevance checks to any retry. Missing TTS leaves visible guidance available with an explicit voice-unavailable state. Do not assume Bahasa Indonesia exists on every installed engine or that provider English instructions become Indonesian solely by changing the TTS locale.

Do not keep the display awake. A foreground service is not itself a CPU wake lock. Prefer short callback work; if a measured screen-off gap requires a partial wake lock, declare `WAKE_LOCK`, acquire with a bounded timeout around the necessary operation and release reliably. Avoid an unbounded whole-trip lock and battery-optimization exemption requests by default. [Wake-lock guidance](https://developer.android.com/develop/background-work/background-tasks/awake/wakelock).

## Reopen, service restart and stop semantics

Persist an atomic session checkpoint (ID, selected route/revision, maneuver progress, consumed prompts, active/ended state). Reopening the activity attaches to the live service state rather than starting a second subscription.

Recommended first implementation: `START_NOT_STICKY`, retaining a recoverable interrupted-session checkpoint if the process dies. On next visible launch, show **navigation interrupted** and offer explicit Resume; resume rechecks permissions, starts a fresh FGS and waits for a fresh fix. This handles reopening honestly without claiming continuous guidance during downtime. If automatic system restart is later chosen, `START_STICKY` may deliver a null intent and needs persisted state; system restarts of sticky FGS have a documented exception to the background-start restriction, but app-initiated starts do not inherit it. Neither mode guarantees immediate restart or survival of force-stop. [Service lifecycle API](https://developer.android.com/reference/android/app/Service).

Android's user Stop action may terminate the app without cleanup callbacks. Never rely solely on `onDestroy()` to mark the session stopped; distinguish persisted intent from a currently live service. Do not auto-resurrect tracking from a boot receiver, alarm or stale checkpoint. [User-initiated FGS stop](https://developer.android.com/develop/background-work/services/fgs/handle-user-stopping).

An explicit OMOX End action atomically ends the session, removes location updates/deadline tasks, stops and releases TTS/audio focus, removes the foreground notification and stops the service. Late callbacks must carry a session generation and be ignored. Trip recording from #31 may share navigation fixes while both are active, but ending navigation must not silently destroy an independently active recording; keep ownership explicit.

## Evidence required before closing #32

1. Deterministic location replay verifies progress, maneuvers, duplicate suppression, crossings, off-route, stale/poor fixes, interrupted speech and end-session late callbacks.
2. On the dedicated physical TECNO, start from the foreground, turn the screen off, verify location-driven guidance and native service continuation, reopen without duplicate subscriptions, then Stop and verify no continued navigation location/speech. USB may supply installation/observation only, not routing or navigation backend.
3. Exercise permission denial, disabled location, unavailable TTS/audio interruption and process death/reopen. Replay fixtures must be explicitly labelled; a stationary indoor phone is not evidence of live road guidance accuracy.
4. TECNO Android 11 cannot prove API 33 notification-denial or API 34–35 launch-enforcement behavior. Cover SDK guards through source/tests and report that platform validation limit; do not use an emulator without the user's explicit request.
