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
3. Request permissions from your own host-app UX when needed
4. Drive safety flows using SDK methods and streams (SOS, device, tracking, contacts)

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 — the app secret must never be in the mobile client.

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

HTTP auth:

X-App-ID: <appId>
X-User-ID: <externalUserId>
Authorization: Bearer <userHash>

MQTT auth (no Bearer prefix):

username: sdk:<appId>:<externalUserId>
password: <userHash>

Bootstrap

Minimal example

final sdk = await EixamConnectSdk.bootstrap(
  const EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.sandbox,
    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

Optional:

• initialSession — signed session to apply immediately
• customEndpoints — required when environment is custom
• enableLogging
• networkTimeout
• defaultLocaleCode

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

nota

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
• 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()
Diagnostics	getOperationalDiagnostics(), watchOperationalDiagnostics()
Device	connectDevice(), getDeviceStatus(), deviceStatusStream
SOS	triggerSos(), cancelSos(), getCurrentSosIncident(), getSosState()
Contacts	listEmergencyContacts(), createEmergencyContact(), updateEmergencyContact()
Permissions	getPermissionState(), requestLocationPermission(), …
Protection Mode	evaluateProtectionReadiness(), enterProtectionMode(), getProtectionStatus()
Realtime	getRealtimeConnectionState(), watchRealtimeEvents()
Device registry	listRegisteredDevices()