> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clariodesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating into your Flutter app

> How the SDK behaves from first launch to logout, and how to wire it into an app that already has users.

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](/quickstart). This page is the "why and when" behind those calls.

## The lifecycle at a glance

```mermaid theme={null}
flowchart TD
    A[App launches] --> B["ClarioDesk.init(apiKey)"]
    B --> C{First launch ever?}
    C -->|Yes| D["Generate hardware key,<br/>register device"]
    C -->|No| E["Reuse stored key<br/>(no network)"]
    D --> F{Is a user signed in?}
    E --> F
    F -->|Yes| G["identify(externalId, email)"]
    F -->|No| H["Anonymous device"]
    G --> I["Live use:<br/>streams + optimistic sends"]
    H --> I
    I --> J{Logout or switch user?}
    J -->|Yes| K["reset()"]
    K --> A
    J -->|No| I
```

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 `Stream`s. See [Architecture](/concepts/architecture) for the full picture.

## 1. The first launch

`ClarioDesk.init()` is the first thing to run, before any support UI.

```dart theme={null}
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](/concepts/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:

```dart theme={null}
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:

| Scenario                                                            | What to do                                                                                                                    |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| New user signs in or signs up                                       | Call `identify` right after your auth succeeds.                                                                               |
| User was already signed in before you added (or updated to) the SDK | Call `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 in                                       | Call `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 changed                                  | Call `identify` again with the new values to update the device row.                                                           |

<Tip>
  One habit covers the whole table: identify on every launch whenever you have a
  session, and again right after a fresh login.
</Tip>

### 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:

<CodeGroup>
  ```dart Identify on launch (correct) theme={null}
  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);
  }
  ```

  ```dart Identify only on login (misses existing users) theme={null}
  // Runs only for users who sign in AFTER this build ships.
  onLoginSuccess((user) {
    ClarioDesk.identify(externalId: user.id, email: user.email);
  });
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## 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.

```dart theme={null}
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](/concepts/realtime) for the connection
states.

## 4. Logout and user switching

When the user signs out, call `reset` before clearing your own session:

```dart theme={null}
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:

```dart theme={null}
await ClarioDesk.reset();
await ClarioDesk.init(apiKey: 'pk_live_…');
await ClarioDesk.identify(externalId: userB.id, email: userB.email);
```

<Warning>
  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.
</Warning>

## 5. Relaunches and reinstalls

| After this                   | Device identity                                                     | Ticket history                 |
| ---------------------------- | ------------------------------------------------------------------- | ------------------------------ |
| A normal relaunch            | Same device; key reused with no network                             | Visible to the user            |
| `reset()` (logout or switch) | Wiped; next `init()` makes a fresh device                           | Detached from this device      |
| An uninstall and reinstall   | The stored key may be gone, so `init()` can register a fresh device | Starts 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

<CardGroup cols={2}>
  <Card title="Lifecycle event reference" icon="user-check" href="/flutter/lifecycle">
    The same four events as a tight code reference.
  </Card>

  <Card title="API reference" icon="code" href="/flutter/api-reference">
    Every method, stream, and type.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/concepts/authentication">
    Why the device key replaces tokens.
  </Card>

  <Card title="Realtime" icon="bolt" href="/concepts/realtime">
    Live reads, optimistic sends, and the offline outbox.
  </Card>
</CardGroup>