Understand new-delivery alerts
While Orders is mounted, Driver App can show an in-app overlay for a new or updated order event. The overlay can include a title, a masked order reference, an illustration, vibration, sound, and a close icon.
Viewing or closing this overlay does not accept, reject, acknowledge, read, or change an assignment or order. It also does not prove push receipt, realtime delivery, current request eligibility, location publication, or notification- provider success.
Availability
The overlay listens to internal event notifications while the order area is mounted. The same overlay system can present new-message, new-order, order- update, assignment-register, or assignment-update events with different copy.
Whether an alert appears can depend on authenticated session state, event shape, current app lifecycle, notification/realtime setup, provider configuration, native platform behavior, and—when any subscribed event payload contains Driver data—a current-location attempt. The Driver overlay does not use the Business App's status-filter branch as a general suppression rule.
State and result matrix
| Visible or source state | What it means | Safe response | What remains unproven |
|---|---|---|---|
| No overlay | No current event is being presented by this component. | Continue from the current order state. | That no event, push, or assignment exists |
| New-order overlay | A local event handler selected new-order presentation with an order reference. | Read the masked reference; close if needed. | Receipt source, eligibility, assignment, or currentness |
| Order-updated overlay | A local event handler selected update presentation. | Recheck the order list/detail separately. | Which field changed or whether the update is final |
| New-message overlay | A local event handler selected message presentation. | Use the conversation guide. | Send authorization, delivery, visibility, or read receipt |
| Event payload with Driver data | The handler can try to get and publish current location before later event-type filtering or overlay selection. | Do not use the alert as a location, message, order, or assignment receipt. | Location freshness/storage/broadcast and event/assignment state |
| App active with overlay | The component can vibrate and repeatedly play remote or native alarm sound. | Use the close icon once if you need to stop the local overlay. | Media/provider success or restoration of device sound settings |
| Overlay closed | Current local overlay state is cleared and component cleanup is requested. | Verify only that the overlay is no longer visible. | Acknowledgment, rejection, read state, push state, or assignment change |
| Push opened | Root can interpret supported payload shapes and request a detail route. | Verify the actual visible screen. | Push delivery guarantees, deep-link support, or detail data success |
Effects and boundaries
| Boundary | Source-defined behavior | Public limit |
|---|---|---|
| EventContext/realtime | Emits local event names consumed by the overlay. | Event intent does not prove transport receipt, ordering, or freshness. |
| Overlay state | Stores one current event and clears it from the close icon. | Dismissal is local presentation only. |
| Sound/vibration/media | Active overlay can vibrate, load remote sound, use a native alarm module, and show a bundled illustration. | Viewing is not passive or hermetic; playback success is unproven. |
| Android notification path | Can raise alarm volume to maximum for an incoming remote notification and does not restore the prior value in reviewed source. | Do not claim the device's prior volume is preserved. |
| Location | Any subscribed event payload containing Driver data can request coordinates and publish them before event filtering or overlay selection. | Collection, freshness, mock handling, storage, broadcast, and order effects are separate and blocked. |
| Push token | Authenticated provider setup can obtain/store/register a notification token. | Prompt, token, registration, push delivery, opened event, and overlay are distinct. |
| Assignment/order | Alert can refer to an order or assignment request. | It is not an Accept/Reject/status action or eligibility decision. |
View and dismiss safely
- Read only the visible alert type and masked order reference.
- Do not select an order, assignment, message, map, contact, or status action based only on the alert.
- Select the close icon once to dismiss the local overlay.
- Verify only that the overlay is no longer visible.
- Open Orders or the relevant task guide separately if you need to confirm current state.
Do not use real push, assignment, location, sound, or notification-provider traffic to test this behavior. A simulator does not isolate those effects.
Platform and lifecycle variations
- Sound and vibration run only while the component considers the app active.
- Android can use a native alarm path; other cases can use the sound-player path. Both depend on device/provider availability.
- Android incoming remote notifications can alter the alarm volume without a reviewed restoration step.
- iOS notification permission and banner presentation have separate startup/ Settings boundaries.
- Backgrounding or foregrounding can change whether sound/vibration runs, but it does not prove event acknowledgment or cleanup.
Troubleshooting
| What you see | What to check | Safe recovery |
|---|---|---|
| No alert for an expected delivery | App lifecycle, notification/realtime configuration, permissions, event shape, connectivity, and current order list | Do not send a test order or change assignment state. Check the current list and escalate with sanitized time/platform only. |
| Alert appears for an unexpected status | The Driver overlay does not apply the Business status-filter branch generally. | Close it and verify the current order/request in its owning screen. |
| Alert closes but the order state is unclear | Dismissal changes only local overlay state. | Do not repeat or infer an action; use the order/detail guide. |
| Sound or vibration continues | Native/media cleanup or app lifecycle did not settle as expected. | Close once, move away from the alert, and use device-safe controls; report platform/app version without identifiers. |
| Android alarm volume changed | The reviewed native notification path can raise alarm volume without restoring it. | Adjust volume through normal device controls and report the behavior; do not trigger another alert. |
| Location error appears before an alert | The event payload contained Driver data, so the handler attempted current-location work before later filtering or presentation. | Do not change location, message, order, or assignment state to retry; use the location guide and escalate. |
| Opening a push leads somewhere unexpected | Payload shape and current root state control supported navigation. | Verify the visible screen; do not use the push as a deep link or success receipt. |
Related guides: Driver App overview · Navigate the Driver App · Active delivery · Location permissions · View order conversations