Quickstart

Get up and running with the Eixam Flutter SDK in five steps.

1. Add the dependency

Use the immutable Eixam release ref provided during handoff:

dependencies:
  eixam_connect_flutter:
    git:
      url: https://github.com/eixam-tech/eixam-sdk-flutter
      ref: YOUR_EIXAM_SDK_RELEASE_REF # Replace with the supplied tag or commit.
      path: packages/eixam_connect_flutter

2. Import the package

import 'package:eixam_connect_flutter/eixam_connect_flutter.dart';

3. Bootstrap the SDK

Your backend must generate the signed session — the app secret must never live in the mobile client.

Create the notification copy from your app localization layer and pass it during bootstrap. Values must be non-empty because native foreground services and Protection Mode notifications can render them while Flutter is backgrounded:

const notificationTexts = EixamNotificationTexts(
  protectionActiveTitle: 'EIXAM protection active',
  protectionActiveBody: 'Sharing your safety status in the background.',
  protectionModeTitle: 'EIXAM Protection Mode',
  protectionModeBody: 'Keeping your device connected for SOS alerts.',
  protectionModeChannelName: 'Protection mode',
  protectionModeChannelDescription:
      'Keeps protection available in the background.',
  protectionSosChannelName: 'Protection SOS',
  protectionSosChannelDescription: 'Alerts from your protected device.',
  protectionPreSosTitle: 'SOS pre-alert',
  protectionPreSosBody: 'Your device reported a possible SOS.',
  protectionSosActiveTitle: 'SOS active',
  protectionSosActiveBody: 'Your device has activated SOS.',
  protectionSosResolvedTitle: 'SOS resolved',
  protectionSosResolvedBody: 'The device SOS has ended.',
);

Standard environment

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

Custom environment

final sdk = await EixamConnectSdk.bootstrap(
  EixamBootstrapConfig(
    appId: 'partner-app',
    environment: EixamEnvironment.custom,
    notificationTexts: notificationTexts,
    customEndpoints: EixamCustomEndpoints(
      apiBaseUrl: 'https://partner-api.example.com',
      mqttUrl: 'ssl://partner-mqtt.example.com:8883',
    ),
  ),
);

Signed session

The backend generates userHash by signing externalUserId with the app secret using HMAC-SHA256. See Identity Signing for implementation examples.

4. Request permissions

Permission requests are explicit host-app decisions — the SDK does not trigger them on its own. Ask only when the user starts the capability that needs the permission; avoid presenting three native prompts at app startup:

// For example, immediately before the user starts device pairing:
await sdk.requestBluetoothPermission();

Use the SDK disclosure preflight before the native prompt. The Permissions Checklist includes the store-friendly flow for Bluetooth, location, and notifications.

5. Use the SDK

Trigger an SOS:

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

Connect a device:

await sdk.connectDevice(pairingCode: '123456');

After connection, use DeviceStatus.isReadyForSafety and the typed capability streams to decide which actions to show. Do not infer readiness from the BLE device name or connection icon alone.

Create an emergency contact:

await sdk.createEmergencyContact(
  name: 'Mountain Rescue Desk',
  phone: '+34600000000',
  email: 'rescue@example.com',
  language: 'es',
);

Limit

Each user can have at most 5 emergency contacts. Attempting to create a 6th contact fails with HTTP 409 Conflict — delete an existing contact before adding a new one.

Important notes

aviso

• initialSession is optional. If provided, its appId must match the bootstrap appId.
• notificationTexts is required and every field must be non-empty.
• Do not pass customEndpoints to non-custom environments.
• Bootstrap does not request permissions or trigger UX-sensitive actions.

Where to go next

Goal	Guide
Complete the recommended app architecture	Recommended Integration Path
Add user-confirmed device firmware updates	Firmware Updates / OTA
Handle country-aware LoRa radio configuration	LoRa Radio Region
Configure Android/iOS permissions	Permissions Checklist
Diagnose a failed integration	Troubleshooting