App-link boundaries
Customer App can receive a project-configured app link and ask its navigation system to open a recognized destination. Recognition is only the first step: it does not prove that the current customer can access the target, that the target exists, or that opening it is free of product effects.
App-link handling remains source-reviewed and pre-action. Use project-issued links only. Do not hand-build, publish, or execute a Customer App link until the current build, destination authorization, fallback, and lifecycle behavior have passed an approved isolated verification.
Separate each responsibility
| Layer | Responsibility | What it does not prove |
|---|---|---|
| Operating system | Delivers a configured link to an installed app when platform registration matches. | That Customer App recognizes the route or can open its target. |
| Customer App parser | Classifies a received link and extracts the input required by a known route class. | Target ownership, availability, freshness, or business eligibility. |
| Customer App navigation | Applies startup, account, verification, profile, project, and connectivity gates before presenting a screen. | That the screen's data read or action succeeded. |
| Ordering services | Authorize the current customer and return the permitted business, cart, or order state. | Operating-system delivery or provider completion. |
| Destination owner | Defines the visible result, failure states, safe return path, and any product or provider effect. | That every other route has the same behavior. |
Current route classes
The pinned Customer App source declares the following route classes. This table describes intent, not a runnable public URL contract.
| Route class | Intended destination | Required authority | Important boundary |
|---|---|---|---|
| Start | The app's main account or start navigation. | Current app/project and startup state. | Profile completion, verification, tutorial, sign-in, and location prerequisites can appear first. It is not a guaranteed public Home shortcut. |
| Business | A business browsing screen. | A project-issued business reference plus current location, order context, and business availability. | A recognized link does not prove that the business is available to the customer. |
| Product within a business | A product handoff through the business journey. | Project-issued business, category, and product context that belongs together. | Current handling is not certified as passive. Do not publish product-target links until the destination effect firewall is accepted. |
| Checkout | Checkout for an accessible cart. | Current account or authorized guest context, exact project, and server-authorized cart. | A cart reference is not a capability token. Opening checkout can begin provider- and recovery-sensitive reads. |
| Order details | Details for an authorized order. | Current account or an independently approved temporary-access contract. | A route reference is not proof of ownership. The order response and any tracking, messaging, or payment data remain separately authorized. |
| Unsupported | The app's general link fallback. | None. | The current build does not establish a reliable customer-visible fallback. Do not promise a Page Not Found screen or a specific return destination. |
Treat parser input as untrusted
Only consume a link generated by the approved project or Ordering-owned workflow. Before navigation, the integration must:
- Match the configured app and project without exposing their identifiers.
- Reject unknown route classes, extra fields, incomplete input, malformed encoding, and values outside the public contract.
- Bind sensitive intent to the current account or authorized guest context, session generation, project, destination, and expected resource.
- Apply freshness and one-time-use rules where a link can reach sensitive data or a consequential journey.
- Authorize the target before mounting a screen that performs reads, opens a provider, or can change a cart or order.
- Consume the intent once and clear it on logout, account switch, project switch, or failed validation.
Never place passwords, payment information, provider credentials, session tokens, notification tokens, private customer data, or precise location data in an app link.
Follow the handling sequence
| Stage | Expected result | Failure owner |
|---|---|---|
| Platform delivery | The configured build receives the link. | Mobile build and operating-system registration. |
| Parse | One known route class with a complete, typed input. | App-link parser owner. |
| Readiness | Navigation is ready and the intended project/account generation is current. | Startup, routing, and session owners. |
| Authorization | Ordering confirms that the caller can access the target. | Destination API/security owner. |
| Presentation | The destination shows its own loading, available, unavailable, or error state. | Destination product owner. |
| Completion | Any requested action or provider result is reconciled with authoritative Ordering state. | Destination mutation/provider owner. |
A later stage must not be inferred from an earlier one. In particular, delivery does not prove parsing, parsing does not prove authorization, and visible navigation does not prove completion.
Handle lifecycle and account gates
Cold launch, foreground open, background return, duplicate delivery, and an already-running app can produce different timing. Queue an accepted intent only until navigation is ready, bind it to the current session/project generation, and consume it once.
Account and experience gates remain authoritative. A customer may first see sign-in, account verification, profile completion, location setup, or another prerequisite. Do not bypass those gates or replay the original intent after the customer changes account or project unless the server authorizes it again.
Plan for unavailable and unsupported targets
| Observable result | Safe interpretation | Next engineering action |
|---|---|---|
| The app does not open | Platform registration, installed build, or scheme ownership is unverified. | Confirm the intended build and project without publishing the link value. |
| The app opens somewhere unexpected | Parsing, startup priority, or stale navigation state is unverified. | Record the route class and app state with identifiers removed; do not repeatedly reopen it. |
| A prerequisite appears | The destination remains gated. | Complete only the visible supported prerequisite, then reauthorize the target. |
| The destination reports unavailable | The route can be recognized while its resource or current context is unavailable. | Use the destination's own recovery contract; do not edit or guess the link. |
| A link is unsupported or malformed | No reliable Customer App fallback is currently established. | Stop processing and return through trusted in-app navigation. |
| An error follows a cart, checkout, or order handoff | The operation outcome can be ambiguous. | Reconcile authoritative cart/order state before any retry. |
Verify without live effects
An approved verification must use a non-production build or a pure parser adapter, reserved non-resolving references, an inert destination recorder, and zero provider or product effects. Cover:
- accepted and rejected route classes;
- complete, missing, extra, malformed, and oversized input;
- signed-out, signed-in, guest, verification, and profile-completion gates;
- correct and stale account/project generations;
- cold, warm, background, duplicate, and replayed delivery;
- unavailable and unauthorized resources without existence leaks;
- safe return and accessible focus on iOS and Android; and
- zero cart, checkout, order, payment, notification, provider, or storage mutation before explicit destination authorization.
Do not use a real customer, business, cart, order, notification, or provider identifier as documentation evidence.
Revalidate when the contract changes
Repeat the isolated review when route classes or inputs change, native scheme registration changes, a destination gains a new automatic read or mutation, account/project gates change, notification routing changes, or the unsupported link fallback is repaired.
Troubleshooting
A link works on one build but not another
Treat each build and project configuration separately. Confirm that the link was issued for the intended build; do not copy its private values into logs or tickets.
A product link opens a business but not Product Details
Do not assume the product input was complete or that Product Details is the only valid branch. Keep product-target links disabled until the current destination contract is certified as passive and complete.
Checkout or order details are unavailable
Recognition does not authorize the cart or order. Verify the current account, project, and the resource through trusted in-app navigation. Do not substitute another reference or retry a consequential action.
An unsupported link has no visible error
That is within the current blocked fallback boundary. Stop processing the link and return through trusted app navigation rather than promising a fallback.
Related references: Customer routing behavior · Invalid and unavailable app links · Configuration and experience boundaries · Native integration boundaries · Payment boundaries