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

astuce

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.