Public API

Import only the public Flutter entrypoint:

import 'package:eixam_connect_flutter/eixam_connect_flutter.dart';

This page lists the public SDK surface for new integrations.

Tags:

Core: expected in most integrations.
Optional: use only when the product enables that capability.
Advanced: support, diagnostics, validation tooling, or custom runtime setup.

Bootstrap

API	Returns	Use
`EixamConnectSdk.bootstrap(config)`	`Future<EixamConnectSdk>`	Standard partner bootstrap
`initialize(config)`	`Future<void>`	Advanced custom factory setup only

final sdk = await EixamConnectSdk.bootstrap(
  EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.sandbox,
    notificationTexts: notificationTexts,
    initialSession: EixamSession.signed(
      appId: 'partner-app',
      externalUserId: 'partner-user-123',
      userHash: 'signed-session-hash',
    ),
  ),
);

The example assumes notificationTexts is a non-empty EixamNotificationTexts value supplied by the host app.

Bootstrap validates appId, environment/endpoints, notificationTexts, and initialSession.appId. It does not request permissions, pair devices, or trigger safety actions.

Session

API	Returns	Use
`setSession(session)`	`Future<void>`	Store/replace signed SDK identity
`clearSession()`	`Future<void>`	Clear persisted SDK identity
`getCurrentSession()`	`Future<EixamSession?>`	Read current session
`refreshCanonicalIdentity()`	`Future<EixamSession>`	Re-fetch identity from `GET /v1/sdk/me`

The app secret never belongs in the mobile app. Your backend signs externalUserId and gives the app userHash.

Profile

API	Returns	Use
`fetchSdkUserProfile()`	`Future<SdkUserProfile>`	Load profile from `GET /v1/sdk/me`
`updateSdkUserProfile(update)`	`Future<SdkUserProfile>`	Partial update via `PUT /v1/sdk/me`

Use SdkProfileValidators for local form checks and ProfileHttpException.fieldHints for backend field errors.

Diagnostics

API	Returns	Use
`getOperationalDiagnostics()`	`Future<SdkOperationalDiagnostics>`	Read current session/realtime/SOS/device bridge diagnostics
`watchOperationalDiagnostics()`	`Stream<SdkOperationalDiagnostics>`	Observe runtime diagnostic changes

Useful fields: connectionState, backendSosAvailable, deviceSosAvailable, canActivateSos, currentSosCapabilityLabel, lastPublicSosDeliveryChannel, lastTelRelayRx, and bridge.

Background Telemetry (Optional)

API	Returns	Use
`enableBackgroundTelemetry({notificationTitle, notificationBody})`	`Future<void>`	Enable SDK background telemetry where supported
`disableBackgroundTelemetry()`	`Future<void>`	Disable SDK background telemetry

If notificationTitle or notificationBody is omitted, the SDK uses EixamBootstrapConfig.notificationTexts.protectionActiveTitle and protectionActiveBody.

Inspect status through SdkOperationalDiagnostics.backgroundTelemetryEnabled, androidForegroundServiceRunning, and related background fields.

Protection Mode (Optional)

API	Returns	Use
`evaluateProtectionReadiness()`	`Future<ProtectionReadinessReport>`	Check blockers before arming
`enterProtectionMode({options})`	`Future<EnterProtectionModeResult>`	Arm Protection Mode
`exitProtectionMode()`	`Future<ProtectionStatus>`	Disarm Protection Mode
`getProtectionStatus()`	`Future<ProtectionStatus>`	Read current protection state
`watchProtectionStatus()`	`Stream<ProtectionStatus>`	Observe state changes
`getProtectionDiagnostics()`	`Future<ProtectionDiagnostics>`	Read detailed native/runtime diagnostics
`watchProtectionDiagnostics()`	`Stream<ProtectionDiagnostics>`	Observe diagnostic changes
`rehydrateProtectionState()`	`Future<ProtectionStatus>`	Restore native runtime state after restart/resume
`flushProtectionQueues()`	`Future<FlushProtectionQueuesResult>`	Flush queued native SOS/telemetry

Android provides the strongest background BLE ownership. iOS support is capability-aware and may report partial coverage.

Device Lifecycle

API	Returns	Use
`connectDevice(pairingCode: ...)`	`Future<DeviceStatus>`	Pair/reconnect selected device
`disconnectDevice()`	`Future<void>`	Disconnect active device runtime
`preferredDevice`	`Future<PreferredDevice?>`	Read remembered preferred BLE device
`activateDevice(activationCode: ...)`	`Future<DeviceStatus>`	Activation flow when required by the integration
`getDeviceStatus()`	`Future<DeviceStatus>`	Read latest cached device status
`refreshDeviceStatus()`	`Future<DeviceStatus>`	Force status refresh
`deviceStatusStream`	`Stream<DeviceStatus>`	Observe device lifecycle changes

For normal onboarding, prefer connectDevice(). Use DeviceStatus.isReadyForSafety for a compact readiness signal.

Firmware Updates (Optional)

API	Returns	Use
`getFirmwareInfo({deviceId})`	`Future<DeviceFirmwareInfo>`	Read connected device firmware, hardware, battery, and readiness context
`checkFirmwareUpdate({deviceId, policy})`	`Future<FirmwareUpdateCheck>`	Check release availability and SDK eligibility blockers
`startFirmwareUpdate(deviceId:, releaseId:, policy:)`	`Future<FirmwareUpdateSession>`	Start a user-confirmed update for a release returned by `checkFirmwareUpdate(...)`
`watchFirmwareUpdateProgress({deviceId})`	`Stream<FirmwareUpdateProgress>`	Observe download, verification, transfer, reconnect, installed-version verification, failure, cancellation, or recovery state
`cancelFirmwareUpdate(sessionId)`	`Future<void>`	Request cancellation for a cancellable session

Firmware updates are explicit user actions. Host apps should check availability when a connected device is ready, show blockers from FirmwareUpdateEligibility, and only call startFirmwareUpdate(...) after the user confirms. Do not mark an update complete from app UI alone; rely on the SDK session/progress state after installed-version verification.

For integration flow, platform notes, cancellation, and recovery guidance, see Firmware Updates / OTA.

Device SOS & Commands (Optional / Advanced)

API	Returns	Use
`getDeviceSosStatus()`	`Future<DeviceSosStatus>`	Read device-side SOS state
`watchDeviceSosStatus()`	`Stream<DeviceSosStatus>`	Observe device-side SOS state
`triggerDeviceSos()`	`Future<DeviceSosStatus>`	Device-only SOS trigger command
`confirmDeviceSos()`	`Future<DeviceSosStatus>`	Confirm device pre-SOS
`cancelDeviceSos()`	`Future<DeviceSosStatus>`	Cancel device SOS
`acknowledgeDeviceSos()`	`Future<DeviceSosStatus>`	Acknowledge device SOS
`sendInetOkToDevice()`	`Future<void>`	Tell device internet is available
`sendInetLostToDevice()`	`Future<void>`	Tell device internet is unavailable
`sendPositionConfirmedToDevice()`	`Future<void>`	Confirm position availability
`sendSosAckRelayToDevice(nodeId: ...)`	`Future<void>`	ACK relay SOS for a node
`sendShutdownToDevice()`	`Future<void>`	Request device shutdown
`setDeviceNotificationVolume(volume)`	`Future<void>`	Set notification buzzer volume, `0..100`
`setDeviceSosVolume(volume)`	`Future<void>`	Set SOS buzzer volume, `0..100`
`getDeviceRuntimeStatus()`	`Future<DeviceRuntimeStatus>`	Read typed device runtime status
`getRuntimeIdentitySnapshot()`	`Future<RuntimeIdentitySnapshot>`	Inspect command-capable BLE identity
`rebootDevice()`	`Future<void>`	Request device reboot

Use public SOS APIs for normal app-originated SOS flows. Device command APIs are for explicit device UX, support, and validation.

Device Registry (Optional)

API	Returns	Use
`listRegisteredDevices()`	`Future<List<BackendRegisteredDevice>>`	List backend device records
`upsertRegisteredDevice(...)`	`Future<BackendRegisteredDevice>`	Create/update backend device record
`deleteRegisteredDevice(deviceId)`	`Future<void>`	Delete backend device record

The SDK may also sync paired devices automatically when a canonical hardware id is available.

Pre-SOS (Optional)

API	Returns	Use
`startPreSos({countdown})`	`Future<void>`	Start pre-SOS countdown, default 20s
`confirmPreSos(payload)`	`Future<SosIncident>`	Confirm countdown and create SOS
`cancelPreSos()`	`Future<void>`	Cancel countdown
`getPreSosStatus()`	`Future<PublicPreSosStatus?>`	Read current pre-SOS state
`watchPreSosStatus()`	`Stream<PublicPreSosStatus?>`	Observe pre-SOS state

API	Returns	Use
`handleOsSosWidgetActivation(activation, {countdown})`	`Future<OsSosWidgetActivationResult>`	Handle a validated Android/iOS widget activation through the SDK-owned SOS lifecycle

Use this only after the host app has validated the native widget payload and confirmed that the app session is allowed to enter the SOS flow. The recommended default is a guarded countdown or app-open confirmation model. The widget must not call backend routes, parse BLE/device data, cancel/resolve SOS, or route to emergency services directly.

For native setup and guardrails, see OS SOS Widget.

SOS

API	Returns	Use
`triggerSos(payload)`	`Future<SosIncident>`	Create SOS through backend, device, or both
`cancelSos()`	`Future<SosIncident>`	Cancel active SOS
`resolveSos()`	`Future<void>`	Resolve active SOS
`acknowledgeSosSummary()`	`Future<SosState>`	Acknowledge SDK-facing summary state
`getCurrentSosIncident()`	`Future<SosIncident?>`	Read active/recent incident
`getSosState()`	`Future<SosState>`	Read public SOS state
`currentSosStateStream`	`Stream<SosState>`	Observe public SOS state
`lastSosEventStream`	`Stream<EixamSdkEvent>`	Observe latest SOS-related events
`listSosHistory({cursor, limit})`	`Future<SosHistoryPage>`	Read paginated SOS history

await sdk.triggerSos(
  const SosTriggerPayload(
    message: 'Need assistance',
    triggerSource: 'button_ui',
  ),
);

Contacts

API	Returns	Use
`listEmergencyContacts()`	`Future<List<EmergencyContact>>`	Load contacts
`watchEmergencyContacts()`	`Stream<List<EmergencyContact>>`	Observe contact list refreshes
`createEmergencyContact(...)`	`Future<EmergencyContact>`	Create contact
`updateEmergencyContact(contact)`	`Future<EmergencyContact>`	Update contact
`deleteEmergencyContact(contactId)`	`Future<void>`	Delete contact
`reorderEmergencyContacts(ids)`	`Future<void>`	Set escalation order; include every id once

Contacts are backend-owned SDK resources.

Permissions

API	Returns	Use
`getPermissionState()`	`Future<PermissionState>`	Read aggregated permission state
`requestLocationPermission()`	`Future<PermissionState>`	Request location permission
`requestNotificationPermission()`	`Future<PermissionState>`	Request notification permission
`requestBluetoothPermission()`	`Future<PermissionState>`	Request Bluetooth permission

The host app declares native permissions and owns the UX timing for permission requests.

Notifications (Optional)

API	Returns	Use
`initializeNotifications()`	`Future<void>`	Initialize SDK local notifications
`showLocalNotification(title:, body:)`	`Future<void>`	Show a simple local notification
`consumePendingBleNotificationNavigationRequest()`	`Future<BleNotificationNavigationRequest?>`	Consume queued BLE notification navigation
`watchBleNotificationNavigationRequests()`	`Stream<BleNotificationNavigationRequest>`	Observe BLE notification navigation
`consumePendingNotificationIntents()`	`Future<List<EixamNotificationIntent>>`	Consume queued notification intents
`watchNotificationIntents()`	`Stream<EixamNotificationIntent>`	Observe notification intents

EixamNotificationPolicy.hostAppManaged lets the host app own SOS lifecycle notifications, but native foreground-service notification copy is still supplied through EixamNotificationTexts.

Tracking & Telemetry (Optional)

API	Returns	Use
`startTracking()`	`Future<void>`	Start tracking
`stopTracking()`	`Future<void>`	Stop tracking
`publishTelemetry(payload)`	`Future<void>`	Publish telemetry
`getCurrentPosition()`	`Future<TrackingPosition?>`	Read current position
`getTrackingState()`	`Future<TrackingState>`	Read tracking state
`watchPositions()`	`Stream<TrackingPosition>`	Observe positions
`watchTrackingState()`	`Stream<TrackingState>`	Observe tracking state

Telemetry location should follow the SDK Location Authority model. Manually built publishTelemetry(payload) calls should not republish cached fallback, backend snapshot, stale device, invalid, or out-of-context remote relay coordinates.

Death Man Protocol (Optional)

API	Returns	Use
`scheduleDeathMan(...)`	`Future<DeathManPlan>`	Schedule DMP plan
`getActiveDeathManPlan()`	`Future<DeathManPlan?>`	Read active plan
`confirmDeathManCheckIn(planId)`	`Future<void>`	Confirm user is safe
`cancelDeathMan(planId)`	`Future<void>`	Cancel plan
`watchDeathManPlans()`	`Stream<DeathManPlan>`	Observe plan changes

Events & Realtime (Advanced)

API	Returns	Use
`watchEvents()`	`Stream<EixamSdkEvent>`	Observe high-level SDK events
`getRealtimeConnectionState()`	`Future<RealtimeConnectionState>`	Read realtime transport state
`getLastRealtimeEvent()`	`Future<RealtimeEvent?>`	Read last realtime event
`watchRealtimeConnectionState()`	`Stream<RealtimeConnectionState>`	Observe realtime connection lifecycle
`watchRealtimeEvents()`	`Stream<RealtimeEvent>`	Observe raw realtime events

Advanced Factories (Advanced)

ApiSdkFactory is exported for controlled setups and validation tooling. Most partner apps should use EixamConnectSdk.bootstrap(...).

Bootstrap​

Session​

Profile​

Diagnostics​

Background Telemetry (Optional)​

Protection Mode (Optional)​

Device Lifecycle​

Firmware Updates (Optional)​

Device SOS & Commands (Optional / Advanced)​

Device Registry (Optional)​

Pre-SOS (Optional)​

OS SOS Widget (Optional)​

SOS​

Contacts​

Permissions​

Notifications (Optional)​

Tracking & Telemetry (Optional)​

Death Man Protocol (Optional)​

Events & Realtime (Advanced)​

Advanced Factories (Advanced)​