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. Deprecated compatibility aliases are listed separately at the end.

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, {deferRuntimeWork})`	`Future<void>`	Store/replace signed SDK identity; optionally defer reconnect/runtime work until authenticated UI is ready
`startDeferredRuntime()`	`Future<void>`	Start runtime work deferred by `setSession(...)`
`clearSession()`	`Future<void>`	Clear persisted SDK identity
`clearLocalUserData()`	`Future<void>`	Idempotently clear SDK-owned local data without calling remote deletion endpoints
`getCurrentSession()`	`Future<EixamSession?>`	Read current session
`refreshCanonicalIdentity()`	`Future<EixamSession>`	Re-fetch identity from `GET /v1/sdk/me`
`deleteUserData(userHash:, externalUserId:)`	`Future<void>`	Delete SDK-owned remote user data and clear SDK-local data during account deletion

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

clearSession() is logout. deleteUserData(...) is account erasure and must be coordinated with partner-auth deletion and app-local cleanup. The SDK clears its local user data even if the remote erasure request fails; surface the remote failure so the user can retry or contact support.

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`
`submitAppFeedback(description:, userAccessToken:)`	`Future<AppFeedbackSubmission>`	Submit authenticated in-app feedback; requires the current Eixam user JWT, not SDK HMAC-only auth

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
`getSosCapability()`	`Future<SosCapabilitySnapshot>`	Read authoritative app/device SOS activation capability
`watchSosCapability()`	`Stream<SosCapabilitySnapshot>`	Observe capability changes
`retrySosCapability()`	`Future<SosCapabilitySnapshot>`	Explicitly retry capability readiness after a recoverable failure
`getResolvedLocationForEmergencyContext()`	`Future<SdkResolvedLocation?>`	Read the SDK-selected location for emergency UI/context
`watchResolvedLocation()`	`Stream<SdkResolvedLocation?>`	Observe location authority changes

Useful fields: connectionState, backendSosAvailable, deviceSosAvailable, canActivateSos, currentSosCapabilityLabel, lastPublicSosDeliveryChannel, resolvedLocation, deviceCountryConfig, 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
`scanBleDevices({timeout})`	`Future<List<EixamBleScanResult>>`	Scan for typed Eixam/DFU devices without parsing advertisements in host code
`getBleDiagnostics()`	`Future<EixamBleDiagnostics>`	Read BLE support diagnostics
`watchBleDiagnostics()`	`Stream<EixamBleDiagnostics>`	Observe BLE diagnostics
`getDeviceCommandChannelStatus()`	`Future<BleCommandChannelStatus>`	Read whether device commands are currently available
`watchDeviceCommandChannelStatus()`	`Stream<BleCommandChannelStatus>`	Observe command-channel readiness
`preferredDevice`	`Future<PreferredDevice?>`	Read remembered preferred BLE device
`bootstrapPreferredDeviceReconnect(...)`	`Future<PreferredDeviceReconnectResult>`	Perform the startup reconnect attempt
`startPreferredDeviceReconnectMonitor(...)`	`Future<void>`	Start SDK-owned reconnect monitoring after BLE readiness
`stopPreferredDeviceReconnectMonitor()`	`Future<void>`	Stop reconnect monitoring
`reconnectPreferredDevice(...)`	`Future<PreferredDeviceReconnectResult>`	Request a typed reconnect attempt/result
`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.

LoRa Radio Region (Optional)

API	Returns	Use
`getDeviceCountryConfigStatus()`	`Future<DeviceCountryConfigStatus>`	Read the latest per-country radio-config status
`watchDeviceCountryConfigStatus()`	`Stream<DeviceCountryConfigStatus>`	Observe detection, apply, reboot, and verification outcomes
`checkDeviceCountryConfig({reason, countryIsoOverride})`	`Future<DeviceCountryConfigStatus>`	Detection-only check; never writes or reboots
`applyPendingDeviceCountryConfig({reason})`	`Future<DeviceCountryConfigStatus>`	Apply a pending mismatch after explicit user confirmation

The SDK performs best-effort detection when a connected device becomes command-capable, but never applies a change automatically. countryIsoOverride is for controlled development tools, not production country selection. See LoRa Radio Region.

Firmware Updates (Optional)

API	Returns	Use
`getFirmwareInfo({deviceId})`	`Future<DeviceFirmwareInfo>`	Read connected device firmware, hardware, battery, and readiness context
`listFirmwareReleases({deviceId})`	`Future<List<FirmwareRelease>>`	List compatible backend releases for controlled support/development tooling
`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
`registerDeviceIdentityMapping(hardwareId:, nodeId:, source:)`	`Future<void>`	Register a stable hardware/node identity mapping for advanced runtime integration
`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
`triggerSosAuthoritatively(payload)`	`Future<SosActivationResult>`	Return the typed activation result used by host UX that must distinguish confirmed and pending paths
`cancelSos()`	`Future<SosIncident>`	Cancel active SOS
`cancelSosAuthoritatively()`	`Future<SosCancellationResult>`	Return the typed cancellation result across available paths
`resolveSos()`	`Future<void>`	Resolve active SOS
`acknowledgeSosSummary()`	`Future<SosState>`	Acknowledge SDK-facing summary state
`getSosLifecycle()`	`Future<SosLifecycleSnapshot>`	Read the authoritative persisted SOS lifecycle
`sosLifecycleStream`	`Stream<SosLifecycleSnapshot>`	Observe lifecycle changes
`getCurrentSosIncident()`	`Future<SosIncident?>`	Read active/recent incident
`getCurrentSosIncidentProgress()`	`Future<SosIncidentProgress?>`	Read realtime-backed incident progress when available
`currentSosIncidentProgressStream`	`Stream<SosIncidentProgress?>`	Observe incident progress with a public fallback for custom runtimes
`getCurrentSosTerminalReason()`	`Future<SosTerminalReason?>`	Read why the latest lifecycle became terminal
`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
`preparePermissionPreflight(requirement)`	`Future<EixamPermissionPreflightResult>`	Determine required disclosure/native action before prompting
`acceptPermissionDisclosure(requirement)`	`Future<EixamPermissionPreflightResult>`	Record disclosure acceptance and continue the planned native action
`declinePermissionDisclosure(requirement)`	`Future<EixamPermissionPreflightResult>`	Record decline and return limited-feature guidance
`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. Prefer the preflight APIs when the product must show an explanation before the native prompt. See the Permissions Checklist.

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
`getResolvedTelemetryPreview({includeCachedFallback})`	`Future<SdkTelemetryPayload?>`	Build a resolver-backed preview and inspect authority before raw publish
`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(...).

Deprecated compatibility aliases

New integrations should avoid these aliases:

Deprecated	Replacement
`pairDevice(...)`	`connectDevice(...)`
`unpairDevice()`	`disconnectDevice()`
`watchDeviceStatus()`	`deviceStatusStream`
`ensureDeviceCountryConfig(...)`	`checkDeviceCountryConfig(...)`, then explicit `applyPendingDeviceCountryConfig(...)`
`watchSosState()`	`currentSosStateStream`
`addEmergencyContact(...)`	`createEmergencyContact(...)`
`removeEmergencyContact(...)`	`deleteEmergencyContact(...)`

Bootstrap​

Session​

Profile​

Diagnostics​

Background Telemetry (Optional)​

Protection Mode (Optional)​

Device Lifecycle​

LoRa Radio Region (Optional)​

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)​

Deprecated compatibility aliases​