Visión general del SDK

El Eixam Connect SDK es la capa de integración embebible de la plataforma de seguridad conectada Eixam. Posee la lógica central de seguridad y runtime para que tu app anfitriona pueda mantenerse ligera y centrada en la UX.

El modelo mental para el partner es simple:

1. Bootstrap del SDK una sola vez al iniciar la app
2. Proporcionar una sesión firmada obtenida desde tu backend
3. Solicitar permisos desde la UX de tu propia app anfitriona cuando sea necesario
4. Gestionar flujos de seguridad usando métodos y streams del SDK (SOS, dispositivo, tracking, contactos)

Sesiones firmadas y responsabilidades del backend

El SDK usa un modelo de sesión firmada para autenticarse en los transportes HTTP y MQTT. Tu backend es el propietario del paso de firma — el secreto de la app nunca debe estar en el cliente móvil.

Responsabilidad	Propietario
Almacenar el secreto de la app	Backend del partner
Firmar userHash para appId + externalUserId	Backend del partner
Recibir y reenviar la sesión firmada	App móvil
Reutilizar identidad para HTTP y MQTT	SDK

Auth HTTP:

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

Auth MQTT (sin prefijo Bearer):

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

Bootstrap

Ejemplo mínimo

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ón
production	Entorno de producción
sandbox	Desarrollo y pruebas
staging	Pre-producción
custom	Endpoints gestionados por el partner

EixamBootstrapConfig

Obligatorio:

• appId
• environment

Opcional:

• initialSession — sesión firmada a aplicar inmediatamente
• customEndpoints — obligatorio cuando environment es custom
• enableLogging
• networkTimeout
• defaultLocaleCode

Endpoints personalizados

Usa EixamEnvironment.custom junto con EixamCustomEndpoints cuando controles tu propia infraestructura:

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

nota

mqttUrl y websocketUrl son los nombres de campo estables. La URI del broker puede usar ssl://, tls://, tcp://, ws:// o wss:// según el entorno y el cliente de transporte.

Garantías del bootstrap

• Los entornos estándar resuelven la configuración de endpoints internamente
• Los endpoints personalizados se validan antes de usarlos
• Las sesiones restauradas con discrepancias se limpian automáticamente
• El SDK mantiene el control de la semántica del ciclo de vida de la sesión
• El bootstrap no solicita permisos en tiempo de ejecución ni realiza emparejamiento de dispositivos por sí solo

Capacidades

Categoría	Métodos
Sesión	setSession(), clearSession(), getCurrentSession()
Diagnósticos	getOperationalDiagnostics(), watchOperationalDiagnostics()
Dispositivo	connectDevice(), getDeviceStatus(), deviceStatusStream
SOS	triggerSos(), cancelSos(), getCurrentSosIncident(), getSosState()
Contactos	listEmergencyContacts(), createEmergencyContact(), updateEmergencyContact()
Permisos	getPermissionState(), requestLocationPermission(), …
Modo Protección	evaluateProtectionReadiness(), enterProtectionMode(), getProtectionStatus()
Tiempo real	getRealtimeConnectionState(), watchRealtimeEvents()
Registro de dispositivos	listRegisteredDevices()