Use the reviewed location contract
Driver App location is not one capability. It includes device collection, one-shot reads, watches, in-memory route lines, map presentation, foreground publication, background-provider publication, status-embedded location, server storage/broadcast/trails, validation, mock policy and retention.
Keep each lane separate. Source presence or a passing client validation does not prove fresh, trusted, mock-safe, stored, broadcast, shared, retained or deployed location behavior.
Availability
Location work depends on effective platform permission, authenticated identity, project/status configuration, lifecycle, user availability, map/detail mount, provider readiness and connectivity. Several components start a one-shot read or watch on mount, before the Driver presses a location or status control.
Prerequisites
- Product/privacy purpose and minimum-collection approval for each lane.
- Effective iOS/Android permission and lifecycle review.
- Current account/session generation and request authorization.
- Explicit coordinate, timestamp, accuracy and mock provenance.
- Server policy for normalization, freshness, mock handling, storage, availability broadcast, customer sharing, order trail and retention.
- Deterministic watch/listener/provider cleanup and zero sensitive logs.
Responsibility boundaries
| Lane | Client responsibility | Limit |
|---|---|---|
| One-shot read | Ask device provider for high-accuracy current position with timeout/cache inputs. | Returned coordinate/timestamp/mock is not inherently trusted. |
| Foreground watch | Start/stop position watch and update local route/current state. | Multiple starts can overwrite one watch ID and leave an earlier watch. |
| Map mount | Read/watch location and publish non-zero coordinate updates through client SDK. | Mount/focus is effectful; no freshness/mock metadata in that save shape. |
| Delivery detail/form | Start watch, validate selected statuses and optionally embed location in status request. | Client pass is not server trust or status acceptance. |
| Root direct refresh | Read device location and publish with authenticated Driver context. | AppState/touch/provider callbacks can trigger it. |
| Background provider | Configure/start/stop tracking and HTTP callbacks from permission/token/user/language state. | Setup/start/callback/cleanup are separate and currently cleanup-blocked. |
| API | Authorize/normalize/mock-check/store/broadcast/trail according to lane/config. | Running artifact mapping remains unknown. |
Inputs and result
| Input/state | Possible result | Critical limit |
|---|---|---|
| Device coordinates | Local latitude/longitude/speed/mock and sometimes timestamp | Root and UI hooks produce different timestamp shapes. |
| Watch event | Update current location and append in-memory route line | Accuracy/provenance/retention and duplicate-watch cleanup unproven. |
| Map location update | SDK save with coordinate object | No timestamp/mock in reviewed map save. |
| Direct/background publication | Authenticated location request/provider HTTP | Storage/broadcast/trail and mock/freshness differ by server lane. |
| Status location | Location embedded with target status | Can skip separate timestamp/mock checks; trail failure need not fail status. |
| Client validation | Missing/stale/target/distance issues or local pass | Mock/accuracy/trust/server decision not established. |
| Unauthorized provider response | Local logout intent | Session/provider/API cleanup is partial. |
Security and privacy
- Never log or persist precise coordinates, route lines, raw provider/HTTP responses, tokens, addresses or account/order data in documentation evidence.
- Treat collection, current/last storage, availability broadcast, customer sharing, order effects, history and retention as separate approvals.
- Reject stale/unknown timestamp, insufficient accuracy and unreviewed mock provenance before trusted use.
- Bind watches/callbacks/late results to the current account and screen lifecycle.
- A simulator is not hermetic and mock location is not automatically safe.
Limits and failure states
| State | Meaning | Maintainer response |
|---|---|---|
| Missing/denied permission | Client/provider cannot use intended lane. | No bypass; use permission contract. |
| Zero/missing coordinate | Hook normalization or no usable result. | Do not publish/infer location. |
| Missing timestamp | Some hook/save lanes omit it. | Do not call fresh. |
| Mock indicator | Captured in some device/provider lanes. | Client validation does not reject it; server policy required. |
| Watch started while not focused | Map mount effect can start before focus. | Fix/test ownership and cleanup. |
| Multiple watch starts | Single stored watch ID can be overwritten. | Prove every watch is cleared. |
| Status succeeds but trail fails | C08 partial effect. | Never equate primary write with durable trail. |
| Provider HTTP unauthorized | Local logout intent. | Reconcile location/session/provider cleanup. |
Troubleshooting
| Symptom | Inspect | Safe diagnostic |
|---|---|---|
| Location updates before map is focused | Mount/focus effects and watch count | Use intercepted provider and listener ledger only. |
| Duplicate updates | Multiple follow calls, stored watch ID and cleanup | Count synthetic watch registrations/clears. |
| Client says valid but location is doubtful | Timestamp, accuracy, mock provenance, target and server policy | Stop before status/publication. |
| Map and background locations differ | Hook shapes, cache/timeout, provider, lifecycle and publication lane | Do not reconcile with real coordinates. |
| Status changed without expected trail | Primary C05/C08 versus trail/storage/broadcast follow-ons | Escalate to API/security owner; do not retry. |
Re-review whenever permission, hook result shape, timestamp/mock/accuracy, watch/focus cleanup, map save, status validation, Root/background publication, server storage/broadcast/trail or retention changes.
Related guides: Location permissions · Location validation · Delivery map · Background execution · Maps contract