Installations and identity
Engage creates an anonymous installation before your application knows who is signed in. Identity is added later by binding that installation to a profile.
Why identity is server-mediated
A mobile method such as setUserId("customer_123") would let an untrusted client claim any identity. Engage instead uses a short-lived, single-purpose binding code:
The mobile app sends the code only to your own authenticated backend. Your backend derives the external ID from its authenticated session rather than trusting an ID in the app request.
Request a binding code
val bindingCode = Engage.installation.issueBindingCode()
accountApi.bindEngageInstallation(bindingCode)Treat the code as short-lived sensitive data. Do not log it or store it in analytics.
Commit from your backend
Your backend calls POST /v1/installation-binding-transitions with a service access key, an idempotency key, the binding code, and the external ID. See the complete identity binding API guide.
Generations and account changes
Identity changes advance the installation generation. SDK mutations are generation-aware so operations produced for an old account are not silently applied to the new account. On logout, use your server identity flow rather than trying to delete or regenerate the installation ID.
Installation ID
The SDK exposes its server-issued installation ID for diagnostics. It is not a login token and should not be used as your product’s user ID.
Engage.installation.id.collect { id ->
diagnostics.engageInstallationId = id
}One profile can have many installation IDs. Reinstalling the app can create a new installation unless valid recovery state is available.