Core Concepts
Foundational concepts behind the Eixam SDK design and integration model.
SDK-first
Eixam is built SDK-first. The SDK owns the core safety and runtime logic. The host app consumes that logic through stable, documented contracts without reimplementing any of it.
Bootstrap vs session lifecycle
Bootstrap
bootstrap(...) creates the SDK instance and resolves environment configuration. It runs once at app start.
Session lifecycle
These methods manage the signed identity after bootstrap:
| Method | Description |
|---|---|
setSession(...) | Apply a new or refreshed signed session |
clearSession() | Remove the current session |
getCurrentSession() | Read the current signed session |
Signed identity vs canonical identity
Signed identity
Provided by the partner backend:
| Field | Description |
|---|---|
appId | Application identifier |
externalUserId | User identifier, unique per app |
userHash | HMAC-SHA256 signature of externalUserId |
Canonical identity
The SDK can enrich the signed identity through GET /v1/sdk/me. Internal runtime flows use this canonical backend identity for transport and topic resolution.
Standard vs custom environments
Use standard environments whenever possible:
| Environment | Use case |
|---|---|
production | Live deployments |
sandbox | Development and integration testing |
staging | Pre-production validation |
custom | Self-managed or partner-controlled endpoints |
Only use EixamEnvironment.custom when you explicitly control alternative endpoints.
Runtime-sensitive actions
Some capabilities are deliberately UX-sensitive and must remain explicit host-app decisions. The SDK does not trigger these on its own:
- Requesting permissions
- Entering Protection Mode
- Device pairing and connection
- Starting tracking
- Showing partner-branded UI flows
Validation app vs partner app
The validation app is an internal thin host used to test and observe SDK behavior. It is not the reference product UX for partners.