Use the reviewed notifications contract
Driver notifications span provider configuration, OS permission, device subscription, local token state, API registration, remote push, opened payloads, EventContext overlays, navigation, sound, vibration, and native alarms. These lanes can settle independently and none is an order or assignment receipt.
This contract is source-api-only. It documents responsibilities without
running provider, token, location, notification, navigation, sound, or alarm
effects.
Availability
| Surface | Current public boundary |
|---|---|
| Provider setup | Conditional on authenticated state and configured Driver notification app identity |
| Permission | OS/provider prompt and device state are distinct from subscription and delivery |
| Token | Provider subscription/device identifier can be stored locally and submitted to the authenticated token contract |
| Push opened | Supported payload shapes can select an ordinary or logistics detail navigation intent |
| Group payload | A grouped payload is cleared without navigation in current source |
| Event overlay | Mounted Orders can present local message/order/request copy from EventContext |
| Sound and vibration | Overlay can invoke timers, vibration, remote/native playback while active |
| Android alarm | Native paths can change alarm volume; previous volume restoration is not established |
Prerequisites
- Require an authenticated Driver session and reviewed public configuration; never embed provider identifiers or credentials in documentation.
- Treat permission, subscription, token observation, local storage, API registration, provider delivery, opened callback, overlay, and navigation as separate states.
- Validate payload identity, authorization, freshness, and supported target before navigation or order work.
- Keep location, assignment, messages, order status, read receipts, tokens, and notification acknowledgments outside documentation runtime.
- Replace provider, OS, native media, timer, vibration, navigation, storage, and network layers before any future controlled evidence.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Root notification setup | Conditional provider initialization, permission/device state, local token state, registration intent, and opened routing |
| API token contract | Authenticate, validate, and associate the token with the permitted user/app context |
| Push provider | Subscription and delivery transport; not business authorization or completion |
| EventContext/overlay | Select local presentation from subscribed app events and clear local state |
| Navigation | Resolve only supported targets; destination owns fresh authorized data |
| OS/native media | Permission, lifecycle, vibration, sound, alarm category/volume, and cleanup |
| Order/assignment/message owners | Decide authoritative state; never delegate it to a notification |
Inputs and result
Provider and token lane
Authenticated setup can observe a provider subscription/device identifier, store local notification state, and submit a token association. Client loading completion is not an API receipt. A registered token does not prove permission, subscription, provider delivery, payload integrity, or opened behavior.
Push-open lane
Current source distinguishes ordinary order detail from logistics assignment detail using payload fields. A grouped payload does not navigate and the local pending target is cleared after evaluation. Navigation intent does not prove that the destination exists, loads fresh data, authorizes the Driver, or performs an order action.
Event overlay and native effects
Orders can mount an EventContext-driven overlay. Some event shapes can begin a location-publication path before later overlay selection. While an overlay is active, remote/native sound, vibration, timers, or alarms can run. Closing the overlay clears local presentation only; it does not acknowledge, read, accept, reject, assign, or update an order.
Security and privacy
- Never expose provider IDs, tokens, credentials, private payloads, order or assignment identifiers, location, contact data, or native logs publicly.
- Authorize and re-read destination state after navigation; do not trust push or socket payloads as current business data.
- Bind token registration to the authenticated subject and approved app class; define revocation, rotation, logout, multi-device, and stale-token behavior.
- Validate payload schema and discard unsupported/grouped targets safely.
- Restore device state after native alert effects and test cleanup across foreground, background, interruption, dismissal, and unmount.
- Treat provider delivery and native presentation as transport, not consent, authorization, assignment, or completion.
Limits and failure states
| State | Required interpretation |
|---|---|
| Provider configured | Setup may run; not permission/subscription/delivery |
| Permission accepted | Not token registration or delivery |
| Token observed locally | Not authenticated API association |
| Registration request ends | Not successful persistence without authoritative receipt |
| Push received/opened | Untrusted transport event until validated and re-read |
| Group payload | No current navigation target |
| Overlay visible | Local presentation only; not order/request currentness |
| Overlay closed | Local state cleared; no acknowledgment or order effect |
| Sound stops | Cleanup requested; remote/native release and volume restoration unproved |
| Destination opens | Navigation only; data, authorization, and action result remain separate |
Troubleshooting
Notifications are permitted but none arrive
Check configuration, subscription, token observation, local persistence, API association, provider delivery, OS presentation, and app lifecycle separately. Do not rotate or re-register a real token from documentation evidence.
Opening a notification does not navigate
Confirm that the payload belongs to a supported target. Grouped payloads are currently cleared without navigation. Even for supported shapes, destination authorization and fresh data loading remain separate.
The in-app alert is visible without a matching push
EventContext overlays and remote push are different lanes. Overlay visibility does not prove provider receipt, current order state, or assignment eligibility.
Sound or alarm behavior persists
Stop testing and restore device state under the native owner. Current Android source does not establish restoration of the prior alarm volume; no real-device capture is admitted by this contract.
Related guides: View new-delivery alerts · Review device permissions · Driver App architecture · Use the authenticated bootstrap contract · Run governed evidence safely