Rules for AI agents

​

The rules

1. The pk_live_… key is publishable — safe to ship in the app binary. It only authorizes a fresh install to register a device; it cannot read tickets or impersonate users. There is no secret key to hide, no appId parameter, and no server-side environment variable — the key encodes the app. Do not move it to a backend, do not build a key-proxy endpoint.
2. Never build auth for ClarioDesk. There are no JWTs, no refresh tokens, no session endpoints. The SDK generates a non-extractable hardware-backed device key on first launch and signs every request with it (device-is-identity — see Authentication). identify({ externalId, email, traits }) is metadata only and grants no access.
3. Call identify() on every app launch for logged-in users, hydrated from the app’s persisted session — not only in the login flow. Users who were already signed in before the SDK was added never pass through login again; a login-only hook leaves them unlabeled. identify() is idempotent, so repeated calls are correct, not wasteful. Pass the auth system’s stable user id as externalId (Firebase user.uid, Clerk user.id, Auth0 user.sub) — never an auth token, never an email. See Identity lifecycle.
4. Logout: clearIdentity() when Verified identity is enabled; reset() only in label-only mode. Verified account switch = await clearIdentity(), then identify user B with a fresh proof. Label-only legacy switch = acknowledged reset() → init() → identify(). reset() deprovisions the installation — never use it as routine logout when history must follow the user across sessions.
5. Two modes, one install — don’t mix them. Either the prebuilt UI (Flutter: ClarioDeskWidgets.openInbox(context); React Native: @clariodesk/react-native/ui) owns the support screens, or the app’s custom screens built on the headless API do. Don’t hand-roll one screen inside the prebuilt flow.
6. React Native: import 'react-native-get-random-values' must be the first import in the entry file — before any other import, or key generation fails at runtime.
7. Push is a separate package on purpose. React Native push lives in @clariodesk/react-native-push because Firebase’s native code autolinks into every host that installs it — never add it (or any @react-native-firebase/* package) to an app that didn’t opt into push. Flutter receives FCM tokens through the PushTokenProvider seam; the SDK never imports firebase_messaging.
8. Never invent a ticket id in push data. Flutter 0.3.0+ resolves its opaque deliveryId through resolvePushTarget and marks focused routes with setVisibleSupportSurface; never read private ids from raw FCM data. Current React Native/Swift and older Flutter releases validate + refresh, then a custom UI opens its support inbox. Missing visibility wiring may create an extra alert, but must never hide the only support reply.
9. Expo Go is an evaluation lane, not a shipping lane. The SDK transparently falls back to a software P-256 key there (no native modules) and remote push is unavailable. Everything else works. Recommend a dev build (npx expo prebuild && npx expo run:ios) before release.
10. Attachments need iOS usage strings. Enabling the picker means the host app must declare NSPhotoLibraryUsageDescription (plus camera/microphone variants if capture is enabled) in Info.plist.
11. Never guess an API name. The full surface is small and documented — Flutter: API reference; React Native: API reference. Machine-readable index: llms.txt / llms-full.txt; any page is fetchable as markdown by appending .md to its URL. If the ClarioDesk docs MCP server is connected (https://docs.clariodesk.com/mcp — see Install with AI), prefer its search_clario_desk tool over web fetches.

​

Quick facts

​

Integration flow