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.

Use preparePermissionPreflight(...) when your product requires an explanatory screen before the native prompt. Only call the request method after the user accepts that disclosure.

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()
OTA firmware updates	checkFirmwareUpdate(), startFirmwareUpdate(), Firmware Updates / OTA
LoRa radio region	watchDeviceCountryConfigStatus(), applyPendingDeviceCountryConfig(), LoRa Radio Region

Verify Each Milestone

Do not wait until the full product is assembled to validate the integration:

Milestone	Evidence
Bootstrap	SDK instance created with required localized notification copy; no permission prompt appears automatically.
Session	refreshCanonicalIdentity() succeeds and no secret exists in the app bundle.
Permissions	Denied and permanently-denied paths produce useful host UX.
Device	Connect, disconnect, app restart, Bluetooth-off, and preferred-device reconnect behave as expected.
SOS	Trigger/cancel/resolve paths are tested in the agreed non-production environment using typed lifecycle/capability state.
OTA	Availability, blocker, success, transfer interruption, reconnect, and recovery-required UX are tested on each supported platform.
Radio region	Mismatch confirmation, safe deferral, reboot/reconnect, already-up-to-date, and unsupported-firmware outcomes are tested.

Use Troubleshooting and SdkOperationalDiagnostics for support evidence; do not make diagnostics the primary business state.