Recommended Integration Path

Use this path for a new partner app. Add optional capabilities only after the core flow works end to end.

1. Bootstrap Once

Create one SDK instance at app startup and keep it in your dependency container or app state.

final sdk = await EixamConnectSdk.bootstrap(
  EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.sandbox,
    notificationTexts: notificationTexts,
  ),
);

Build notificationTexts from your app localization resources. Each field must be non-empty because Android/iOS runtime paths may render notification copy while Flutter is suspended.

2. Set The Signed Session

Get appId, externalUserId, and userHash from your backend. Never sign inside the mobile app.

await sdk.setSession(
  const EixamSession.signed(
    appId: 'partner-app',
    externalUserId: 'partner-user-123',
    userHash: 'signed-session-hash',
  ),
);

await sdk.refreshCanonicalIdentity();

3. Request Permissions From Your UX

Declare native permissions first, then request them when your app can explain why they are needed.

await sdk.requestLocationPermission();
await sdk.requestNotificationPermission();
await sdk.requestBluetoothPermission();

4. Connect A Device When Needed

Device-backed safety flows start with a partner-selected pairing code.

final status = await sdk.connectDevice(pairingCode: '123456');
if (status.isReadyForSafety) {
  // Enable device-backed safety UI.
}

5. Watch Operational State

Use diagnostics for UI gating and support visibility. Do not recreate transport, BLE, relay, or SOS routing logic in the host app.

sdk.watchOperationalDiagnostics().listen((diagnostics) {
  final canTriggerSos = diagnostics.canActivateSos;
  final channel = diagnostics.currentSosCapabilityLabel;
});

6. Trigger SOS Through The Public API

The SDK chooses backend, device, or backend+device delivery from live capability.

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

Add Optional Capabilities Last

After the core path is stable, add only the capabilities your product needs:

Capability	APIs
Protection Mode	evaluateProtectionReadiness(), enterProtectionMode()
Pre-SOS	startPreSos(), confirmPreSos(), cancelPreSos()
Contacts	listEmergencyContacts(), createEmergencyContact(), reorderEmergencyContacts()
Notifications	initializeNotifications(), watchNotificationIntents()
DMP	scheduleDeathMan(), confirmDeathManCheckIn()