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.co 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
| Responsibility boundary | Supported public boundary | Version limitation |
|---|---|---|
| Business App | Owns registered UI reachability, platform branching, visible state, native-module invocation, and the immediate fallback presented to the operator. | The behavior described here applies to one release-facing revision; it is not proof of an installed binary. |
| Ordering.co Components | Owns shared session, configuration, order, business, event, socket, and API-client state used by the app. | Compatibility depends on the exact paired Components revision. A moving branch does not establish compatibility. |
| Ordering.co API | Owns server authentication, ownership, validation, reads, persistence, logs, jobs, and provider-facing effects for requests that actually reach it. | API behavior described here 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. | Treat any runtime or provider effect as unproven until a single, bounded attempt has an 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. Provider listeners are not consistently removed with the same callback, and not every connection handler is unregistered. | 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 the selection path 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 are established. |
| Maps and geolocation | Request or watch location only from a reachable workflow and render available markers. A stop action is available, but automatic cleanup of an active watch on unmount is not established. | 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; no readback or timed-clearing guarantee is established. |
| 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:
- Establish that the workflow is registered and the current build includes the required native capability.
- Validate project, session, configuration, platform, permission, and purpose-minimal synthetic input before the effect.
- Invoke the handoff once within an explicit effect budget. Include every automatic fallback that one action can start.
- Observe the app result, API result, operating-system/provider result, and physical result independently. One layer must not stand in for another.
- 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.
- 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. Automatic cleanup is not established for every case.
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. This contract 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 release registers it and its authorization, platform/provider behavior, privacy, cleanup, and documentation requirements are established.
Platform, privacy, and error limits
- iOS and Android can use different permission, file, share, print, map, background, and hardware-provider paths. Platform-specific paths exist, but cross-platform parity is not established.
- 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 separates responsibility. It does not establish 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. Record 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 | Confirm the complete version tuple and rerun only the affected synthetic contracts before restoring support. |