Use the reviewed maps contract
Driver maps combine order reads, returned participant coordinates, device location, local grouping, map/image providers, optional Driver-position writes, validation, callout navigation, and external-app handoffs. No one stage proves another.
Marker visibility, distance text, provider render, callout navigation, or an open external app is not location, route, sharing, or completion proof.
Availability
The signed-in Map view is gated by local permission state and a usable initial position. Order details can also open an internal destination map and direct address/provider handoffs.
Opening/focusing maps can start authenticated order reads, GPS/current-position work, location watching, map/image provider loads, and Driver-position request intent. A simulator is not a safe map runtime by default.
Prerequisites
- Authenticated Driver scope and an authorized order context.
- Typed finite coordinates with explicit source, timestamp, trust/mock policy, and purpose.
- Separate permission-request/effective-grant evidence per platform/version.
- Provider adapters denied or replaced for evidence.
- No real address, coordinate, person, order, provider, or route in public fixtures.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Order read API | Return Driver-scoped orders and required participant fields |
| Map controller | Request data, group locally, hold loading/error/pagination state |
| Marker UI | Validate display inputs and present Driver/business/customer groups |
| Location provider | Return device position/watch candidates with platform lifecycle |
| Position API | Authorize Driver self-scope and process location write/effects |
| Map/image provider | Render tiles/assets; never define order/location authorization |
| Callout navigation | Route locally to one detail or list without implying status |
| External handoff | Transfer destination to OS/provider with explicit user choice |
| Product/security/privacy | Define freshness, mock, retention, sharing, provider policy |
Inputs and result
Order read and grouping
Map view requests a fixed source-selected active-status order set, then groups returned orders locally by business and customer identifiers. One marker can represent several orders. Missing/malformed IDs or coordinates can change grouping and route behavior.
Results are loading, blank/unresolved map, Driver-only marker, participant markers, grouped callouts, error, or refresh. None is a complete/current order snapshot.
Device location and writes
The App can request current position/watch. A nonzero candidate can trigger a Driver-position write. Current-source processing can update stored location/ timestamp and conditionally emit sockets, proximity work, and order trails.
Freshness/mock trust and affected status-location success are blocked pending server fixes and negative tests.
Providers and handoffs
Internal maps use a provider and can load remote images. Show in other maps can enumerate provider candidates; direct address links use platform schemes. Declarations/queryability, installation, support, selection, open, route, guidance, arrival, and completion are distinct states.
Security and privacy
- Authorize order and Driver scope before returning coordinates/PII.
- Validate finite ranges, source, freshness, mock policy, timestamp, and intended target before using coordinates for status or sharing.
- Never trust a client marker, permission gate, provider response, or external route as security validation.
- Minimize address/location retention and audience; keep exact provider schemes, identifiers and security findings private.
- Deny GPS, maps, images, address links, installed-app enumeration, sockets, and position writes in documentation fixtures.
Limits and failure states
| State | Required interpretation |
|---|---|
| Blank map | Position/order/provider unresolved |
| Marker at zero/unexpected point | Invalid/stale input possible |
| Grouped callout | Local shared-key grouping, not group authorization |
| Driver marker | Candidate position, not fresh/trusted/server-accepted |
| Position write response | Not socket/trail/customer-visibility completion |
| Provider item | Candidate, not installed/supported |
| Address link | Prepared handoff, not valid route |
| External app open | Provider ownership, not navigation success |
No complete state machine, atomic read/write/provider operation, safe retry, route accuracy, tracking, sharing, retention, or deployed success is established.
Troubleshooting
Markers are missing or grouped incorrectly
Validate typed IDs and finite coordinates in the source record. Do not infer no order or merge/split records from the UI alone.
Driver location looks stale
Treat device candidate, stored location, timestamp, provider render, API write, socket and customer visibility separately. Do not refresh repeatedly.
A provider is listed but does not open
Candidate listing does not prove installation/support. Cancel and use the operator-approved handoff after destination validation.
A direct address opens the wrong place
Stop guidance. Validate address and coordinates through the authoritative order owner; do not edit or try alternate schemes from Driver App.
A map test passes
Confirm the provider/GPS/network/write adapters were inert and the fixture used finite fake data. Otherwise treat it as source support only.
Related guides: Use the delivery map · Open external navigation · Understand location permissions