---
title: "Driver App background execution"
description: "Maintain the reviewed AppState, background-location, permission, session, and listener-cleanup boundaries."
canonical: https://docs.ordering.co/docs/developers/driver-app/background-execution/
---

# Use the reviewed background execution contract

Driver App background execution coordinates AppState changes, local permission state, authenticated account state, language readiness, background-location setup, direct location refresh, account refresh, event logging, and provider callbacks.

Mounting the app or moving it between foreground and background can start work without a task button press. This contract describes source responsibilities only; it does not prove runtime isolation, location delivery, provider success, or a deployed backend.

## Availability

Background-location setup is source-defined only after the Root-local permission gate reports granted, a token is available, and language loading has settled. The reviewed start branch checks ready/disabled state and the local user-enabled flag but does not explicitly require current authentication before it can issue start intent. A later stop branch checks unauthenticated state. Treat explicit authentication-before-start as a required responsibility, not proven behavior.

Requested/declared/effective OS permission, local grant state, provider authorization, location trust, user availability and server acceptance remain separate.

## Prerequisites

- Reviewed native permission declarations and effective merged build state.
- Explicit foreground/background product and privacy requirements.
- Authenticated Driver identity and per-request authorization.
- Zero sensitive logging and clear provider/network egress ownership.
- Deterministic listener/subscription cleanup and account-generation isolation.
- Test location behavior one action at a time in an authorized test environment.

## Responsibility boundaries

| Boundary                | Responsibility                                                                                                                          | Limit                                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Root AppState listener  | Observe active/inactive/background and request configured developer-mode, location, user refresh, permission recheck or event-log work. | Registered once with initial closure state; captured auth/user/loaded values can be stale.                    |
| Permission provider     | Supply current local location-permission state and app-state rechecks.                                                                  | Permission-completeness finding and listener cleanup remain blocked.                                          |
| Background setup        | Configure provider, HTTP/location callbacks, headers, templates, notification and accuracy/lifecycle behavior.                          | Setup is not start, delivery, trust or cleanup success.                                                       |
| Start/stop effect       | Reviewed ordering can request start for ready-disabled plus locally enabled user before the later unauthenticated stop branch.          | Require explicit current auth/account generation before start; source conditions do not prove provider state. |
| Location callback       | Observe provider location events.                                                                                                       | A callback value is not fresh/mock-safe/server-stored proof.                                                  |
| HTTP callback           | Observe provider response, request direct location refresh, and locally logout on unauthorized response.                                | Response/logging/follow-ons can be partial.                                                                   |
| Direct location refresh | Read current device location and request Driver-location publication.                                                                   | C07/C08 trust/storage/broadcast/trail boundaries apply.                                                       |
| API/AppState refresh    | Refresh current user and record background/connectivity events conditionally.                                                           | Captured initial state and failures can suppress or misroute work.                                            |

## Inputs and result

| Input/state                         | Source transition                                                             | Observable/client result              | Limit                                                                         |
| ----------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| Local permission not granted        | Setup returns after clearing local loading.                                   | Provider not configured by that call. | Effective OS state/currentness separate.                                      |
| Missing token                       | Existing provider listeners are requested for removal.                        | No configured authenticated setup.    | Removal completion/provider state unproven.                                   |
| Permission + token + language ready | Follow location and await provider ready.                                     | Ready/enabled state stored locally.   | Provider/server success unproven.                                             |
| Ready, disabled, user enabled       | Start can be requested without an explicit current-auth check in that branch. | Provider state may change later.      | Authentication/account generation and location delivery remain unproven.      |
| Not ready/auth absent/user disabled | Later branch can request stop.                                                | Provider stop intent.                 | Stop ordering cannot erase a prior stale-user start intent; cleanup unproven. |
| AppState active/background/inactive | Handler can request location/user work; background can request event log.     | Async work may begin.                 | Initial closure can hold null user/token/loaded false.                        |
| Provider HTTP unauthorized          | Local logout requested.                                                       | Local auth/navigation can change.     | Server/provider/local cleanup separate.                                       |

## Security and privacy

- Never persist or expose precise coordinates, raw HTTP/provider responses, tokens, user/order data, provider identifiers or verbose location logs.
- Treat location collection, current/last storage, availability broadcast, customer sharing, order trail/effects and retention as separate approvals.
- Do not assume simulator, background mode or provider debug settings are hermetic.
- Bind callbacks and late results to the current account/session generation.
- Require cleanup to remove every location/HTTP/AppState/permission/provider listener and prove no egress remains.

## Limits and failure states

| State                                | Meaning                                          | Maintainer response                                                                        |
| ------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| AppState callback has stale closure  | Listener registered with initial Root values.    | Do not infer current auth/user/loaded behavior.                                            |
| Async setup returns cleanup function | Cleanup is returned by an async function.        | Calling effect does not return/consume it; listeners can remain across dependency changes. |
| Permission listener lacks cleanup    | Provider context can retain lifecycle listener.  | Fix/test before completeness claim.                                                        |
| Provider ready but not started       | Configuration settled, start condition separate. | Keep state explicit.                                                                       |
| Start/stop requested                 | Provider command intent.                         | Verify actual state only in isolated harness.                                              |
| Location/HTTP callback               | Provider supplied data/response.                 | No trust/storage/completion inference.                                                     |
| Unauthorized callback                | Local logout requested.                          | Cleanup/session/provider effects separate.                                                 |

## Troubleshooting

| Symptom                                        | Inspect                                                                   | Safe diagnostic                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Expected AppState refresh does not occur       | Initial closure values, listener mount and current account generation     | Use static trace; do not background a real authenticated app.  |
| Duplicate location/HTTP callbacks appear       | Async setup cleanup consumption and permission-provider listener cleanup  | Count synthetic listener registrations in an isolated harness. |
| Provider shows ready but no location result    | Ready, start, permission, auth, user-enabled and egress states separately | Do not use real coordinates to diagnose.                       |
| Logout occurs after provider response          | HTTP response handling and session cleanup ownership                      | Treat session/provider state as partial until reconciled.      |
| Location appears stored/broadcast unexpectedly | C07/C08 publication, availability and order-trail boundaries              | Stop runtime and use privacy/security review.                  |

Re-review this contract whenever AppState dependencies, permission provider, background setup/start/stop, listener cleanup, location publication, provider callbacks, unauthorized handling or account-generation isolation changes.

**Related guides:** [Device permissions](https://docs.ordering.co/docs/products/driver-app/get-started/device-permissions/) · [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/) · [Authenticated bootstrap](https://docs.ordering.co/docs/developers/driver-app/authenticated-bootstrap/)