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)

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.

:::danger 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
• featureFlags — optional SDK feature flags
• enableLogging

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
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 package to your pubspec.yaml.
2. 🔑 Permissions: Configure your native Android and iOS manifests.
3. 🛠️ Integration: Wire up the bootstrap and session logic.
4. ⚠️ Error Handling: Learn how to handle SDK exceptions and failures.
5. 🔐 Backend Integration: Secure your integration with signed sessions.