Understand location permission states
Customer App source contains location-related controls and native declarations, but those do not establish one current permission state or one cross-platform permission flow. Location permission, a returned coordinate, an address, and a business result are separate states.
:::warning Location information is private
Do not include addresses, coordinates, search text, permission records, device or account identifiers, provider responses, keys, screenshots, or settings details in documentation or diagnostics.
:::
Keep ownership layers separate
| Layer | What it represents | What it does not prove |
|---|---|---|
| Native declaration | A build declares a location purpose or capability | Installed-artifact parity, OS authorization, or a current request |
| OS authorization | The operating system's current decision and scope | App consent, provider consent, a coordinate, or durable availability |
| App-owned state | Loading, disabled, error, toast, fallback, or cached state | The OS decision is unchanged or that another surface agrees |
| Device-location result | A coordinate returned to one native callback | Address ownership, precision, freshness, or permission persistence |
| Reverse-geocode result | A provider translated a coordinate into address data | Saved address, delivery coverage, or trusted current data |
| Map/location display | A map layer or camera used a supplied/cached coordinate | An explicit permission request or accepted business search |
| Saved/order location | Address state owned by account/order/cart surfaces | Device permission, current device position, or provider readiness |
Native declarations differ from runtime authorization. Source inspection also does not prove that iOS and Android prompt, deny, limit, retry, or return from Settings in equivalent ways.
Explicit location action
The pinned address form defines an explicit location control. Activating it enters a loading state and delegates to a native location callback. A successful coordinate can then cross a reverse-geocode provider boundary before the form receives an address candidate.
If native location reports denial, the form can show a denial message. The control can remember that denial for its current mounted lifetime and show the message again without making another native call. This is App-local state, not a fresh OS authorization check.
The source does not define a location-specific Settings action or a complete App-owned request/check/rationale contract. Do not promise a prompt, a Settings handoff, or a successful retry.
Passive discovery and map boundaries
Other pinned discovery surfaces can ask the native location module for a coordinate when they mount or when ordering-location state changes. The map can also request a user-location display from its native map layer and expose a recenter control. These are separate from the explicit address-form action.
A visible recenter control does not prove that a device coordinate exists. A user-location display, far-away notice, or moved camera does not prove that the app deliberately requested permission, that authorization remains current, or that a location was saved.
Denied, unavailable, and unknown states
| State | Safe interpretation |
|---|---|
| Control idle | No current action is established. |
| Loading | A native callback or provider result is pending; authorization is not proved. |
| Denied callback | One native attempt reported denial; OS scope and future eligibility remain platform-owned. |
| App-local disabled | This mounted control suppresses another native attempt; OS state may differ. |
| Native error | Location failed for an unspecified platform reason. |
| Provider error or no result | Reverse geocoding did not produce an accepted address candidate. |
| Coordinate returned | One callback produced location data; address and persistence remain pending. |
| App lifecycle change | Prior callbacks and cached state may be stale. |
| Account/project/session change | Earlier coordinates, providers, and responses must not cross ownership generations. |
Do not repeatedly activate location, open Settings, toggle authorization, or move the map to diagnose an unknown outcome. Use a manual or saved-address alternative when the current surface offers one, and preserve unresolved state as unknown.
Provider and data-minimization boundary
Location can cross several independent destinations: the native location module, map SDK, geocoder, autocomplete or business search. An accepted flow must make each destination and purpose explicit, minimize coordinate precision and query data, avoid passive or duplicate requests, redact telemetry, and reject stale callbacks after account, project, session, permission, consent, or surface changes.
A coordinate, provider response, displayed address, map result, or successful navigation does not establish provider consent, address ownership, serviceability, saved state, or cart settlement.
Accessibility and safe troubleshooting
The location control, loading state, denial/error feedback, manual alternative, map alternative, and Back behavior require independent iOS VoiceOver and Android TalkBack validation. Source does not certify accessible names, roles, busy or disabled state, live announcements, focus return, large-text reflow, keyboard/switch operation, reduced motion, or platform parity.
For safe troubleshooting, record only the value-free state layer that failed: native declaration, OS authorization, App state, native callback, provider result, map display, or saved/order state. Do not collect the location or expose provider error internals. Re-certify after changes to native declarations, permission libraries, address/location controls, automatic discovery reads, map SDKs, geocoding, consent, provider identity, lifecycle cleanup, localization, or shared accessibility primitives.
This page is a source-safe state reference. It does not certify a deployed permission prompt, current authorization, Settings flow, location, provider, address, map, business result, or platform behavior.
Related guides: Understand location selection states · Add or edit an address · Understand map discovery states · Platform and accessibility behavior · Privacy and consent