Driver App 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.
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 | The app clears a grouped payload without navigating |
| 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 valid public configuration; never embed provider identifiers or credentials in app code or shared examples.
- 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.
- Use a non-production account and test provider when exercising workflows that can publish location, change assignments or order status, send messages, or register tokens.
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
Push payload fields distinguish ordinary order detail from logistics assignment detail. 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 in tickets or shared examples.
- 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. Use a test token and provider sandbox when testing registration. Rotating a live token can interrupt notifications on the associated device.
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 the test and restore the device's previous sound settings. Android alarm handling may change the device's alarm volume and may not restore its previous value automatically.
Related guides: View new-delivery alerts · Review device permissions · Driver App architecture · Use the authenticated bootstrap contract