Skip to main content

Android Integration

Android is the most complete platform for Protection Mode and background BLE ownership.

What the SDK owns​

  • Protection method and event channels
  • Foreground-service-backed Protection runtime wiring
  • Merged plugin manifest pieces for the SDK-owned Android path
  • Runtime readiness and diagnostics exposed to Dart

What the host app owns​

  • Runtime permission UX
  • App bootstrap that creates the SDK instance
  • Localized notification copy passed through EixamNotificationTexts
  • Product-specific BLE or safety UX around the SDK
  • Optional OS-level SOS widget registration and app-open forwarding

Required setup​

  1. Declare Bluetooth, location, and notification permissions in AndroidManifest.xml — see the Permissions Checklist
  2. Keep foreground service requirements aligned with your app policy when using Protection Mode
  3. Bootstrap with EixamConnectSdk.bootstrap(...) and non-empty notificationTexts

Optional OS SOS widget​

An Android SOS widget is a host-app entry point into the SDK-owned SOS lifecycle. It should open the app into a guarded SOS flow and forward a validated activation to handleOsSosWidgetActivation(...).

At a safe setup level, the host app provides:

  • An AppWidgetProvider for launcher discovery and rendering.
  • A tap receiver reached through explicit intents.
  • Immutable PendingIntent usage for widget taps.
  • Widget metadata and resources.
  • App launch forwarding into Flutter.
  • Payload validation for source, platform, action id, nonce, timestamp freshness, and confirmation mode.

The widget must not own backend routing, BLE/device logic, cancellation, resolution, or emergency-service routing. Android widget registration does not add dangerous runtime permissions by itself, but normal SOS/location/notification/Bluetooth rules apply if the widget activation becomes an SOS flow.

When validating registration, use a clean install. Android launchers may not discover newly added widget receivers after hot reload or hot restart. See OS SOS Widget for the full integration model.

Protection Mode behavior​

note

Protection Mode is off by default. The host app must arm it explicitly.

  • When armed, Android provides the strongest background path
  • SDK-managed foreground service, Protection Mode, and Protection SOS notification channels use the localized copy from bootstrap
  • Background telemetry uses protectionActiveTitle and protectionActiveBody unless enableBackgroundTelemetry(...) receives explicit notification copy
  • Device-originated active SOS packets can be held in pre-SOS until the countdown boundary; the SDK owns that lifecycle decision
  • Host UI should inspect diagnostics if readiness evaluation is blocked

Location handoff​

Android foreground services and Protection Mode consume SDK-resolved location only when it is fresh, valid, and backend-authoritative. The accepted SDK sources are fresh connectedDevice GPS or phone fallback. Cached fallback, backend incident snapshots, and remote relay locations are display-only or event-scoped and are not accepted as local Android handoff location.

Native Android phone location may also be used when it is fresh and valid. Handoff entries include versioning so stale or incompatible persisted decoder values are rejected. See Location Authority for TTL, coordinate validation, and source-priority details.

Validation checklist​

  1. Bootstrap the SDK
  2. Request permissions explicitly
  3. Connect a device if your flow requires it
  4. Run evaluateProtectionReadiness()
  5. Call enterProtectionMode()
  6. Inspect watchProtectionStatus() and watchProtectionDiagnostics()
  7. Confirm Protection diagnostics show only fresh, valid local handoff location when location is present