Aller au contenu principal

OS SOS Widget

OS-level SOS widgets are optional host-app entry points into the SDK-owned SOS lifecycle. They give users a prominent Android or iOS surface that opens the app into a guarded SOS flow, usually a short PRE-SOS countdown or an app confirmation screen.

The widget is not an independent emergency runtime. It must not own backend routing, BLE or device logic, cancellation, resolution, retry behavior, or emergency-service routing. Those responsibilities remain in the Eixam SDK, backend, and the partner app's reviewed SOS UX.

When to use it​

Use an OS SOS widget when your product needs a faster user entry point than opening the app manually, and when your legal, product, and support teams have approved the user experience.

Good uses:

  • Open the app into the SOS screen.
  • Start a guarded SDK PRE-SOS countdown.
  • Show a small display-only readiness or active-SOS snapshot.
  • Route logged-out users to setup or login instead of triggering SOS.

Avoid:

  • One-tap native SOS without a reviewed guard.
  • Native code that calls backend routes directly.
  • Native code that parses BLE packets or sends device commands directly.
  • Widget snapshots that reveal sensitive status text without approval.

SDK relationship​

The widget should forward a validated activation to the public SDK method:

final result = await sdk.handleOsSosWidgetActivation(
  activation,
  countdown: const Duration(seconds: 10),
);

The SDK then decides how to join the existing SOS lifecycle:

  • If an SOS is already active, return an active-SOS outcome so the app can open the SOS screen.
  • If a PRE-SOS countdown is already running, return the current countdown outcome.
  • If the activation is a duplicate, ignore it.
  • If the activation uses countdown confirmation, start a PRE-SOS countdown.
  • If the activation uses app-open confirmation, require the app to show its confirmation UI.
  • If the activation uses a reviewed hold-style confirmation, activate SOS through the same SDK path as app-originated SOS.

The app should present the result through normal SDK state and routes. Do not create a parallel SOS state machine for the widget.

Public model concepts​

The public SDK exports OsSosWidgetActivation and related enums.

An activation includes:

  • platform: Android or iOS.
  • actionId: stable id for the widget action attempt.
  • nonce: unique fallback id for the tap or intent.
  • timestamp: when the native layer created the activation.
  • confirmationMode: countdown, hold, or app-opened.

The SDK uses the activation idempotency key to dedupe recent actions. Widget-originated SOS payloads use the os_widget trigger source so backend and support systems can distinguish them from in-app button taps.

Activation outcomes include:

  • Countdown started.
  • Countdown already running.
  • Active SOS already running.
  • Activated.
  • Confirmation required.
  • Duplicate ignored.

Android setup​

Android widget support is host-app setup. At a safe integration level, the host app should provide:

  • An AppWidgetProvider that renders the widget.
  • A tap receiver reached only through explicit intents.
  • Immutable PendingIntent usage for widget taps.
  • Widget metadata and resources for the launcher to discover and render the widget.
  • App launch forwarding into Flutter after native validation.
  • Freshness, source, platform, action id, nonce, and confirmation-mode validation before the SDK sees the activation.
  • A clean install when validating widget registration, because Android launchers may not discover new widget receivers after hot reload or hot restart.

The Android widget registration itself does not add dangerous runtime permissions. Normal SDK and SOS permissions still apply if the widget activation becomes an SOS flow that needs location, notifications, Bluetooth, or background behavior.

iOS setup​

iOS widget support is also host-app setup. At a safe integration level, the host app should provide:

  • A WidgetKit extension.
  • An App Group entitlement only for lightweight shared widget state.
  • URL scheme or deep-link handling that opens the app into the guarded SOS flow.
  • AppDelegate and SceneDelegate forwarding for matching widget links.
  • Snapshot sharing from the app to the widget extension.
  • User expectations that WidgetKit refresh timing is controlled by iOS and may be delayed or throttled.

For v1-style WidgetKit home-screen widgets, treat iOS as display and app-open first. Do not rely on the widget extension as a long-running SOS runtime.

Security guardrails​

Every host app integration should enforce these guardrails before forwarding to the SDK:

  • Validate source, platform, action id, nonce, timestamp, and confirmation mode.
  • Reject stale activations and future-dated activations outside a small tolerance.
  • Dedupe action ids and nonces in native and Flutter layers where practical.
  • Require an authenticated app/session state before triggering SDK SOS behavior.
  • Route unauthenticated users to setup or login.
  • Prefer countdown or app-open confirmation by default.
  • Keep snapshots display-only.
  • Avoid sensitive snapshot text unless product/legal has approved it.

Limitations​

OS widgets are convenience entry points, not guaranteed background execution channels. Platform behavior varies by OS, launcher, device policy, and user settings.

Important limits:

  • A widget snapshot is not the source of truth.
  • SDK/backend state remains authoritative.
  • Widget refresh timing can lag behind app state.
  • Opening from a widget may depend on OS behavior.
  • SOS delivery, rescue response, and backend processing must not be described as guaranteed by the widget.