Dokumen ini mencatat tahap implementasi pada versi yang disebutkan. Untuk status akhir seluruh fitur, baca audit implementasi.
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.
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.
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, background start restrictions.
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.
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.
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.
getLastKnownLocationis 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.
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.
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, 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.
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.
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.
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
- Deterministic location replay verifies progress, maneuvers, duplicate suppression, crossings, off-route, stale/poor fixes, interrupted speech and end-session late callbacks.
- 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.
- 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.
- 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.