SDK Overview

The Eixam Connect SDK is the embeddable integration layer of Eixam's connected safety platform. It owns the core safety and runtime logic so your host app can stay thin and focused on UX.

The partner-facing mental model is simple:

1. Bootstrap the SDK once at app startup
2. Provide a signed session obtained from your backend (see Backend Integration)
3. Request permissions from your own host-app UX when needed
4. Drive safety flows using SDK methods and streams (SOS, device, tracking, contacts)

Device firmware and regional radio configuration are also SDK-owned flows: the host presents user confirmation and state, while the SDK owns BLE/DFU commands, safety gates, reconnect, and verification.

For GPS/location behavior, the SDK uses a single Location Authority model across SOS, PRE-SOS/DMP, telemetry, Android foreground/Protection Mode, and UI preview.

Signed Sessions and Backend Responsibilities

The SDK uses a signed-session model to authenticate with both HTTP and MQTT transports. Your backend owns the signing step.

Security

The app secret must never be included or hardcoded in the mobile client. Always perform identity signing on your backend.

Responsibility	Owner
Store the app secret	Partner backend
Sign userHash for appId + externalUserId	Partner backend
Receive and forward the signed session	Mobile app
Reuse identity for HTTP and MQTT	SDK

Bootstrap

Architecture Flow

Minimal example

This snippet assumes notificationTexts is a non-empty EixamNotificationTexts value built from your app localization resources.

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',
    ),
  ),
);

EixamEnvironment

Value	Description
production	Live environment
sandbox	Development and testing
staging	Pre-production
custom	Self-managed endpoints

EixamBootstrapConfig

Required:

• appId
• environment
• notificationTexts — localized non-empty copy for SDK-managed foreground service, Protection Mode, and SOS notifications

Optional:

• initialSession — signed session to apply immediately
• customEndpoints — required when environment is custom
• notificationPolicy — sdkManaged or hostAppManaged
• permissionDisclosureConfig — host-approved pre-permission copy
• featureFlags — optional SDK feature flags
• enableLogging
• allowInsecureLocalEndpoints — controlled local development only

Custom endpoints

Use EixamEnvironment.custom together with EixamCustomEndpoints when you control your own infrastructure:

const EixamCustomEndpoints(
  apiBaseUrl: 'https://partner-api.example.com',
  mqttUrl: 'ssl://partner-mqtt.example.com:8883',
)

note

mqttUrl and websocketUrl are the stable field names. The actual broker URI may use ssl://, tls://, tcp://, ws://, or wss:// depending on environment and transport client.

Bootstrap Guarantees

• Standard environments resolve endpoint configuration internally
• Notification text values are validated before native runtime startup
• Custom endpoints are validated before use
• Mismatched restored sessions are cleared automatically
• The SDK keeps control of session lifecycle semantics
• Bootstrap does not request runtime permissions or perform device pairing on its own

Capabilities

Category	Methods
Session	setSession(), clearSession(), getCurrentSession()
Identity / profile	refreshCanonicalIdentity(), fetchSdkUserProfile(), updateSdkUserProfile()
Diagnostics	getOperationalDiagnostics(), watchOperationalDiagnostics()
Background runtime	enableBackgroundTelemetry(), disableBackgroundTelemetry(), Protection Mode APIs
Device	connectDevice(), disconnectDevice(), getDeviceStatus(), deviceStatusStream, device control APIs
Firmware updates	Firmware Updates / OTA for user-confirmed connected-device update checks, progress, and installed-version verification
LoRa radio region	LoRa Radio Region for country detection, explicit confirmation, device reboot, and verified configuration
Device registry	listRegisteredDevices(), upsertRegisteredDevice(), deleteRegisteredDevice()
Pre-SOS	startPreSos(), confirmPreSos(), cancelPreSos(), watchPreSosStatus()
SOS	triggerSos(), cancelSos(), resolveSos(), getCurrentSosIncident(), getSosState(), listSosHistory()
OS SOS widget	handleOsSosWidgetActivation() for optional guarded Android/iOS widget entry points
Contacts	listEmergencyContacts(), watchEmergencyContacts(), createEmergencyContact(), updateEmergencyContact(), deleteEmergencyContact(), reorderEmergencyContacts()
Permissions	getPermissionState(), requestLocationPermission(), requestNotificationPermission(), requestBluetoothPermission()
Protection Mode	evaluateProtectionReadiness(), enterProtectionMode(), exitProtectionMode(), getProtectionStatus()
Notifications	initializeNotifications(), consumePendingNotificationIntents(), watchNotificationIntents()
Tracking / telemetry	startTracking(), stopTracking(), publishTelemetry(), watchPositions(), Location Authority
DMP	scheduleDeathMan(), confirmDeathManCheckIn(), cancelDeathMan(), watchDeathManPlans()
Realtime	getRealtimeConnectionState(), watchRealtimeEvents()

Next Steps

Now that you understand the mental model, you are ready to integrate:

1. Installation: Add the SDK packages at one immutable release ref.
2. Recommended Integration Path: Build the smallest end-to-end flow.
3. Permissions: Configure native declarations and preflight UX.
4. Backend Integration: Keep signing and secrets on your backend.
5. Error Handling: Map typed exceptions and terminal states to actionable UX.