---
title: "Driver App location contract"
description: "Understand location collection, validation, foreground and background publication, and trust boundaries."
canonical: https://docs.ordering.co/docs/developers/driver-app/location-contract/
---

# Driver App 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.

Each lane has separate permissions, validation, and server effects. A passing client check does not confirm that a location is fresh or trusted, or that it was stored, broadcast, shared, or retained by the server.

## 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.              | Rules and effects can differ by endpoint and configuration.              |

## 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                             | This save does not include timestamp or mock metadata.                       |
| 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 tickets or shared examples.
- Treat collection, current/last storage, availability broadcast, customer sharing, order effects, history and retention as separate approvals.
- Reject stale/unknown timestamps, insufficient accuracy, and untrusted mock locations before using coordinates for a decision.
- 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                  | Some device/provider paths include a mock-location flag. | Client validation does not reject it; server policy is 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](https://docs.ordering.co/docs/products/driver-app/maps/location-permissions/) · [Location validation](https://docs.ordering.co/docs/products/driver-app/maps/location-validation/) · [Delivery map](https://docs.ordering.co/docs/products/driver-app/maps/delivery-map/) · [Background execution](https://docs.ordering.co/docs/developers/driver-app/background-execution/) · [Maps contract](https://docs.ordering.co/docs/developers/driver-app/maps-contract/)