> ## 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 React Native 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, on bare React
Native or Expo. 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 device 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/>subscriptions + 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 (Centrifugo by default,
falling back to SSE).

## 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
subscriptions, or the matching React hooks. See
[Architecture](/concepts/architecture) for the full picture.

## 1. The first launch

`ClarioDesk.init()` runs once at app start. Import the secure RNG polyfill at the
very top of `index.js`, before anything else, then init:

```ts theme={null}
// index.js, before any other import
import 'react-native-get-random-values';
import { ClarioDesk } from '@clariodesk/react-native';

await ClarioDesk.init({ apiKey: 'pk_live_…' });
```

On the very first launch, `init` generates a non-extractable hardware keypair
(Secure Enclave or the Android Keystore on a dev build; a software P-256 key in
Expo Go) 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, and [installation](/react-native/installation) for the secure-storage
peer dependency.

## 2. Identify your user

Once your own auth knows who the user is, hand that down to ClarioDesk:

```ts 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>
  ```ts Identify on launch (correct) theme={null}
  await ClarioDesk.init({ apiKey: 'pk_live_…' });

  // Read the session your app already persisted, then identify on every launch.
  const user = await yourAuth.currentUser();
  if (user) {
    await ClarioDesk.identify({ externalId: user.id, email: user.email });
  }
  ```

  ```ts 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. A hook primes from cache, then re-renders as the agent replies.

```tsx theme={null}
import { useTickets } from '@clariodesk/react-native/hooks';

const { tickets, loading } = useTickets(); // or ClarioDesk.subscribeTickets(cb)
```

Writes are optimistic: a message appears immediately as pending and settles when
the backend confirms (`failed: true` means render tap-to-retry). A send made
while offline waits in a durable outbox and flushes on reconnect. Watch the
realtime link with `useConnection()` 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:

```ts theme={null}
await ClarioDesk.reset();
await yourAuth.signOut();
```

`reset` revokes the device server-side (best effort), wipes the device 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:

```ts 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 device 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:

* [ ] `react-native-get-random-values` is imported first, at the top of `index.js`.
* [ ] `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 `useTickets()` / `useMessages()` (or the prebuilt UI).
* [ ] Optional: `useConnection()` drives an offline indicator.

## Where to go next

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

  <Card title="API reference" icon="code" href="/react-native/api-reference">
    Every method, subscription, hook, and type.
  </Card>

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

  <Card title="Installation & Expo" icon="box" href="/react-native/installation">
    Peer deps, the config plugin, dev build vs Expo Go.
  </Card>
</CardGroup>