Business App native integration safety boundaries

Use this contract when a Business App workflow crosses into device storage, an operating-system surface, a realtime or push provider, a map, or physical output. A bundled native module, visible control, provider identifier, or client request proves only one layer's intent. It does not prove permission, delivery, persistence, external completion, cleanup, or deployed compatibility.

Before you start

• Correlate the installed Business App build with its paired Ordering Components revision and intended API/provider environment.
• Use purpose-minimal synthetic data. Never test with real customer, order, location, message, file, payment, device, notification, or printer identifiers.
• Define one allowed effect, its observer, timeout, rollback or cleanup, and a no-repeat response before invoking a device or provider handoff.
• Treat normal app startup as effect-bearing: API, socket, push, location, and other providers can initialize before an operator selects a control.

Scope and version

Authority	Supported public boundary	Version or pin limitation
Business App	Owns registered UI reachability, platform branching, visible state, native-module invocation, and the immediate fallback presented to the operator.	The reviewed behavior belongs to one release-facing source revision; it is not proof of an installed binary.
Ordering Components	Owns shared session, configuration, order, business, event, socket, and API-client state used by the app.	Only the exact paired Components revision was reviewed. A moving branch is not compatibility authority.
Ordering API	Owns server authentication, ownership, validation, reads, persistence, logs, jobs, and provider-facing effects for requests that actually reach it.	The reviewed API source is not correlated to a deployed environment. Client intent is not a server receipt.
Operating system and third-party provider	Own permission UI, device resources, external-app behavior, delivery, discovery, connection, share/print dialogs, and physical output.	Behavior varies by platform, provider version/configuration, installed modules, device state, and permission.
Integration or release owner	Owns environment configuration, supported build matrix, synthetic fixture, effect budget, observability, redaction, cleanup, and escalation.	No runtime or provider effect is accepted without a serial lease and independent receipt.

Integration responsibility matrix

Integration family	App or Components responsibility	API responsibility	Operating-system or provider responsibility	Required safety boundary
Push notifications	Check permission state, initialize configured provider state, attempt device registration, separate in-app events, and attempt a supported order intent after interaction.	Authenticate and validate eligible device registration and persist it when accepted.	Permission, provider identity, delivery, background behavior, notification interaction, sound, and badge behavior.	Verify permission, registration receipt, delivery, and navigation separately. No delivery or order-opening guarantee.
Realtime sockets	Create a connection from current project/session configuration, join app-owned rooms, and consume events. The reviewed source does not consistently remove provider listeners with the same callback or unregister every connection handler.	Authorize data exposed through normal reads and produce server events where implemented.	Socket transport, connection timing, retries, ordering, duplication, and network availability.	Treat connected state and each event as non-atomic. Count listener registrations/removals and block acceptance on residual or repeated events. Push and realtime are separate transports.
Images and media library	Open the platform image library, hold selected content in app state, preview supported content, and construct a request only for a wired workflow.	Authorize, validate, store, or reject the corresponding profile/message mutation when a request is sent.	Library permission, picker UI, selected asset URI/content, cancellation, and platform encoding.	Minimize content and metadata; cancellation is not failure; no persistence claim before an accepted API result.
Documents and general files	A visible picker may return local file metadata, but this source version does not establish that a selected document is included in the message send contract.	No document-upload responsibility is established for the unconnected selection path.	Picker access, document URI, temporary access, and cancellation.	Do not advertise document attachment or a general file manager. Reopen only after end-to-end wiring, validation, privacy, rendering, and cleanup review.
Maps and geolocation	Request or watch location only from a reachable workflow and render available markers. The reviewed hook exposes an explicit stop action but does not prove that an active watch is cleared automatically on unmount.	Authorize scoped order/business/driver reads and validate any location mutation that is actually sent.	Location permission, accuracy, mocked/stale readings, map tiles, native map behavior, and connectivity.	Coordinates are sensitive. Permission, current position, watcher cleanup, map rendering, and server update are separate results.
External applications	Construct supported web, email, phone, text, or system-settings handoffs from validated visible data.	Own only any prior scoped data read; opening the external application is not an API success.	URL support, target application, user confirmation, call/message/browser/settings behavior, and return to the app.	Preview the destination and data. An open request does not prove the external action completed.
Clipboard	Write the exact operator-selected text from a reachable control.	No clipboard persistence or cleanup contract.	Clipboard availability, retention, sync, and other-app access.	Treat copied order/contact content as sensitive; source shows no readback or timed clearing guarantee.
PDF, share, and system print	Build output from the currently loaded order and invoke the platform branch. A Save / Export PDF attempt can automatically fall back to system print when no file path is returned or an error is caught.	Own the earlier scoped order data only; no server output receipt is established here.	Temporary file creation, share sheet, print dialog, destination app, queue, cancellation, and final output.	Budget PDF creation, share, and fallback print as one combined attempt. A path or dialog is not completion proof; never repeat an ambiguous result and define file cleanup.
Saved and hardware printers	Keep supported local printer configuration, invoke the selected driver, and surface provider-returned status.	No server synchronization is established for the local saved-printer list.	Bluetooth, LAN, USB, discovery, permission, connection, paper, cover, queue, and physical output.	Hardware effects are serial. A toast is not paper proof; manual and automatic paths can duplicate output.
Audio and vibration	Invoke app-owned sound or vibration for eligible in-app/realtime states and remove listeners/timers with the owning lifecycle.	No audio or vibration receipt.	Volume, focus, silent modes, vibration capability, remote sound retrieval, and device policy.	Do not use sound/vibration as delivery or order-state proof; stop repeating output when the state closes.

Lifecycle and outputs

For every native or provider handoff:

1. Establish that the workflow is registered and the current build includes the required native capability.
2. Validate project, session, configuration, platform, permission, and purpose-minimal synthetic input before the effect.
3. Invoke the handoff once within an explicit effect budget. Include every automatic fallback the source can start from that one action.
4. Observe the app result, API result, operating-system/provider result, and physical result independently. One layer must not stand in for another.
5. On timeout, cancellation, rejection, partial state, or unknown result, stop. Do not retry a message, notification registration, external handoff, share, print, or other effect merely to see whether it worked.
6. Remove temporary files and local sensitive state, explicitly stop watchers/listeners/timers where supported, restore permitted local settings, and verify registration/removal counts plus provider, queue, clipboard, or physical residue before accepting cleanup. The reviewed source does not prove every cleanup occurs automatically.

An integration is not complete when a promise resolves, a toast appears, a dialog opens, a socket connects, or a provider returns an identifier. Acceptance requires the effect-specific observer and cleanup receipt defined by the integration owner.

Native product scope

The registered native app supports bounded operator workflows around orders, messages, businesses, profile, sessions, notifications, maps, and printing. Current source evidence does not establish native destinations for general reports, broad administrative settings, a customer directory, or a general file manager.

Shared Components exports, API capabilities, web features, picker controls, and historical work items do not add a native destination. Reopen an excluded outcome only when a later pinned release registers it and its authorization, platform/provider behavior, privacy, cleanup, documentation, and independent runtime review are accepted.

Platform, privacy, and error limits

• iOS and Android can use different permission, file, share, print, map, background, and hardware-provider paths. The source includes platform branches but no cross-platform parity receipt.
• Selected images, document metadata, coordinates, contact details, order content, generated files, copied text, provider identifiers, and printer targets can be sensitive. Keep them out of logs and diagnostic handoffs unless the approved redacted schema requires them.
• Provider and native errors can be returned, caught, reduced to a generic message, logged, or ignored by different call sites. Absence of a visible error is not success.
• Client cleanup can be asynchronous or partial. Unmounting a screen does not by itself prove a provider, watcher, listener, temporary file, queue, clipboard, or physical effect is cleared.
• This contract describes source responsibility at the reviewed versions. It does not certify provider setup, deployed API behavior, installed entitlements, hardware compatibility, or end-to-end completion.

Troubleshooting and escalation

Observable behavior	Owning boundary	Next action
A permission prompt or settings page differs from expected.	Operating system and installed build	Stop; record platform/build and the non-sensitive visible state. Revalidate the platform-specific contract before another attempt.
A picker returns an asset but the later workflow has no confirmed result.	App wiring and API effect	Do not assume upload or persistence. Remove the local selection when safe and inspect the supported request/result contract.
A map appears without a current or accurate position.	Location and map providers	Do not act on inferred coordinates. Verify permission, freshness, accuracy, and scoped API data separately.
An external app or share/print dialog opens without a completion result.	Operating system or destination provider	Treat the result as unknown. Do not repeat; use the destination's approved receipt or escalate.
A printer reports success but output is missing, partial, or duplicated.	Hardware/provider and app invocation	Stop printing, preserve the synthetic queue/paper state, and escalate with the single-attempt receipt.
Sound, vibration, realtime, or push behavior disagrees.	Separate provider lifecycles	Diagnose each transport independently; none proves the others are configured or current.
Realtime events repeat, or location updates continue after the owning view should be inactive.	App listener/watcher lifecycle	Stop the scenario. Capture registration/removal and watcher-start/stop counts, verify residual callbacks without sensitive payloads, and require explicit cleanup before another attempt.
Save / Export PDF opens a print dialog after PDF creation fails or returns no path.	App fallback plus operating-system print	Treat PDF and print as one unresolved attempt. Cancel when safe, do not repeat, and verify temporary-file and print-queue cleanup.
Behavior changes after an app, Components, API, provider, or OS update.	Release and integration owner	Re-pin the complete version tuple and rerun only the affected synthetic contracts before restoring support.

Related articles

• Business App architecture and configuration
• Business App navigation and push boundaries
• Understand notifications and order handoff

:::note Visual status authorized synthetic capture program with accepted exact asset allowlist and independent visual QA :::