Quickstart

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

1. Add the dependency

For the 0.2.0 release, use the agreed Eixam release tag provided during release handoff:

dependencies:
  eixam_connect_flutter:
    git:
      url: https://github.com/eixam-tech/eixam-sdk-flutter
      ref: <agreed-0.2.0-release-tag>
      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',
    ),
  ),
);

:::info 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:

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

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

Create an emergency contact:

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

:::note 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

warning

• 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.