Skip to main content
ClarioDesk is built to drop into an app you have already shipped. This page walks the whole integration, from the very first launch to logout, explains what the SDK does at each step, and covers the case most teams get subtly wrong: an app that already has signed-in users from before ClarioDesk existed. If you just want the fastest path to a working ticket, start with the quickstart. This page is the “why and when” behind those calls.

​
The lifecycle at a glance

Three calls drive everything above: init once at launch, identify when you know who the user is, and reset when they leave. The SDK owns the rest: the device key, the local cache, and the realtime connection.

​
The mental model

The SDK is a thin client that owns four things: a device identity, a local cache, a realtime connection, and (optionally) a set of prebuilt screens. Your app never holds SDK state. You make a few calls in, and reads come back to you as live Streams. See Architecture for the full picture.

​
1. The first launch

ClarioDesk.init() is the first thing to run, before any support UI. 
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await ClarioDesk.init(apiKey: 'pk_live_…');
  runApp(const MyApp());
}
On the very first launch, init generates a non-extractable hardware keypair (Secure Enclave, or the Android Keystore) and registers the device with the backend. That keypair is the device’s identity from then on, and it signs every request. On every later launch, init finds the stored key and reuses it with no network round-trip. See Authentication for how the keypair stands in for tokens.

​
2. Identify your user

Once your own auth knows who the user is, hand that down to ClarioDesk: 
await ClarioDesk.identify(
  externalId: user.id,
  email: user.email,
  traits: {'plan': user.plan},
);
identify is pure metadata. It does not grant access (the device key already did that), so it is safe to call often, and it is idempotent: the same values twice is a no-op.

​
When to call it

The right moment depends on the user’s state when ClarioDesk first runs. Each row below is a real case worth handling:
ScenarioWhat to do
New user signs in or signs upCall identify right after your auth succeeds.
User was already signed in before you added (or updated to) the SDKCall identify on launch from your persisted session. They never pass through login again, so a login-only hook misses them.
No user yet (anonymous)Skip identify. Tickets still work; the device shows as unverified.
Anonymous user later signs inCall identify at that point. The anonymous device and its existing tickets carry forward to the identified user.
Returning signed-in user (relaunch)Call identify again on launch. It is idempotent, so this is a cheap no-op.
The user’s email or traits changedCall identify again with the new values to update the device row.
One habit covers the whole table: identify on every launch whenever you have a session, and again right after a fresh login.

​
The existing-user trap

This is the case most integrations get wrong, so it is worth slowing down on. If you only call identify from your login handler, you label the users who sign in after you ship and nobody else. Everyone who was already logged in when you released the update never visits your login screen again, so they stay unlabeled devices, and your agents see “Unverified device” instead of an email. The fix is to identify from your persisted session on every launch, not from the login event: 
await ClarioDesk.init(apiKey: 'pk_live_…');

// Read the session your app already persisted, then identify on every launch.
final user = await yourAuth.currentUser();
if (user != null) {
  await ClarioDesk.identify(externalId: user.id, email: user.email);
}
Wire identify into your launch path, not just your login path. An “identify on login” hook silently skips every user who was already signed in before you added the SDK.
Skipping identify entirely is fine for anonymous feedback. Tickets still work; they just arrive without an email. When the user signs in later, call identify then and the existing device, and its ticket history, carry forward.

​
3. Live by default

After init (and identify, if you have a user), reads are live. You do not poll. Subscribe to a stream and the SDK primes it from cache, then pushes updates as the agent replies. 
StreamBuilder<List<Ticket>>(
  stream: ClarioDesk.ticketsStream(),
  builder: (_, snap) => /* render the inbox */,
);
Writes are optimistic: a message appears immediately as pending and settles when the backend confirms. A send made while offline waits in a durable outbox and flushes on reconnect. Watch the realtime link with ClarioDesk.connectionStream() to show an offline banner. See Realtime for the connection states.

​
4. Logout and user switching

When the user signs out, call reset before clearing your own session: 
await ClarioDesk.reset();
await yourAuth.signOut();
reset revokes the device server-side (best effort), wipes the hardware key, and clears local caches. The next init registers a brand-new device. For a user switch on the same install (A to B without a restart), do the same and then identify B: 
await ClarioDesk.reset();
await ClarioDesk.init(apiKey: 'pk_live_…');
await ClarioDesk.identify(externalId: userB.id, email: userB.email);
Don’t rebind one device to a second user. reset plus a fresh device is the correct boundary, because each device row carries its own ticket history.

​
5. Relaunches and reinstalls

After thisDevice identityTicket history
A normal relaunchSame device; key reused with no networkVisible to the user
reset() (logout or switch)Wiped; next init() makes a fresh deviceDetached from this device
An uninstall and reinstallThe stored key may be gone, so init() can register a fresh deviceStarts clean on the new device
The takeaway: identity is anchored to the hardware key on a single install. It is not a cloud account that follows the user between devices, so always re-identify on a fresh device to reattach their email and traits.

​
Your integration checklist

For an app already in production:
  • init runs at app start, before any support screen.
  • identify runs on launch from your persisted session, not only on login.
  • reset runs on logout and on user switch.
  • Tickets render from ticketsStream() / messagesStream() (or the prebuilt UI).
  • Optional: connectionStream() drives an offline indicator.

​
Where to go next

Lifecycle event reference

The same four events as a tight code reference.

API reference

Every method, stream, and type.

Authentication

Why the device key replaces tokens.

Realtime

Live reads, optimistic sends, and the offline outbox.