Four moments in your app’s lifecycle interact with the SDK. Wire all four and
the integration is complete. The code below is platform-agnostic; see the
per-SDK lifecycle guides for exact syntax
(Flutter, React Native,
Swift).
1. App launch (every time)
The most common integration miss: users who installed your app before you added
ClarioDesk never go through login again, so an “identify on login” hook alone
leaves them as unlabeled devices.
Hydrate from your own persisted session on launch and identify
unconditionally. identify() is idempotent (same values = no-op write) and
cheap (one signed POST, roughly 5 to 25 ms).
Which value is externalId?
The stable user id your auth system already gives you — the same value its
tokens carry in sub, which is what lets a later upgrade to
Verified identity prove the id you were already
sending:
Never pass an auth token as externalId — tokens rotate, so every refresh
would look like a different person. Never use an email as the id either
(emails change and can be re-registered by someone else; pass it in email:
instead), and avoid guessable ids like sequential integers.
2. Fresh login or signup
Right after your auth succeeds, call identify(). This overwrites the label on
the existing device row, without registering a new device or generating a new
key. The same device now carries the new user’s metadata.
3. Logout
With Verified identity, call
clearIdentity() before signing the user out of your own app.
clearIdentity() preserves the device key, advances the signed identity epoch,
and prevents old-account cache/network work from becoming visible to the next
host user. In label-only mode, reset() remains the stronger shared-device
isolation option.
4. User switch (A → B without restart)
Create and await the clearIdentity() intent, switch the host session, then
verified-identify user B with a fresh proof.
Never activate user B before the clear intent exists, and never fall back to a
label write after proof failure. reset() removes this installation; customer
erasure is a separate owner/admin dashboard action.
What if I never call identify()?
Tickets still work. The device row exists and agents see a device id but no
email, and the dashboard shows an “Unverified device” badge. Useful for
anonymous-feedback flows; otherwise, wire case 1 above. 
