Visió general de l'SDK

L'Eixam Connect SDK és la capa d'integració embebible de la plataforma de seguretat connectada Eixam. Posseeix la lògica central de seguretat i runtime perquè la teva app amfitriona pugui mantenir-se lleugera i centrada en la UX.

El model mental per al partner és simple:

1. Bootstrap de l'SDK una sola vegada en iniciar l'app
2. Proporcionar una sessió signada obtinguda des del teu backend
3. Sol·licitar permisos des de la UX de la teva pròpia app amfitriona quan sigui necessari
4. Gestionar fluxos de seguretat usant mètodes i streams de l'SDK (SOS, dispositiu, tracking, contactes)

Sessions signades i responsabilitats del backend

L'SDK usa un model de sessió signada per autenticar-se en els transports HTTP i MQTT. El teu backend és el propietari del pas de signatura — el secret de l'app mai ha d'estar en el client mòbil.

Responsabilitat	Propietari
Emmagatzemar el secret de l'app	Backend del partner
Signar userHash per a appId + externalUserId	Backend del partner
Rebre i reenviar la sessió signada	App mòbil
Reutilitzar identitat per a HTTP i MQTT	SDK

Auth HTTP:

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

Auth MQTT (sense prefix Bearer):

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

Bootstrap

Exemple mínim

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

Valor	Descripció
production	Entorn de producció
sandbox	Desenvolupament i proves
staging	Pre-producció
custom	Endpoints gestionats pel partner

EixamBootstrapConfig

Obligatori:

• appId
• environment

Opcional:

• initialSession — sessió signada a aplicar immediatament
• customEndpoints — obligatori quan environment és custom
• enableLogging
• networkTimeout
• defaultLocaleCode

Endpoints personalitzats

Usa EixamEnvironment.custom juntament amb EixamCustomEndpoints quan controlis la teva pròpia infraestructura:

const EixamCustomEndpoints(
  apiBaseUrl: 'https://partner-api.example.com',
  mqttUrl: 'ssl://partner-mqtt.example.com:8883',
)

note

mqttUrl i websocketUrl són els noms de camp estables. La URI del broker pot usar ssl://, tls://, tcp://, ws:// o wss:// segons l'entorn i el client de transport.

Garanties del bootstrap

• Els entorns estàndard resolen la configuració d'endpoints internament
• Els endpoints personalitzats es validen abans d'usar-los
• Les sessions restaurades amb discrepàncies es netegen automàticament
• L'SDK manté el control de la semàntica del cicle de vida de la sessió
• El bootstrap no sol·licita permisos en temps d'execució ni realitza emparellament de dispositius per si sol

Capacitats

Categoria	Mètodes
Sessió	setSession(), clearSession(), getCurrentSession()
Diagnòstics	getOperationalDiagnostics(), watchOperationalDiagnostics()
Dispositiu	connectDevice(), getDeviceStatus(), deviceStatusStream
SOS	triggerSos(), cancelSos(), getCurrentSosIncident(), getSosState()
Contactes	listEmergencyContacts(), createEmergencyContact(), updateEmergencyContact()
Permisos	getPermissionState(), requestLocationPermission(), …
Mode Protecció	evaluateProtectionReadiness(), enterProtectionMode(), getProtectionStatus()
Temps real	getRealtimeConnectionState(), watchRealtimeEvents()
Registre de dispositius	listRegisteredDevices()