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

# Identifying users

> Attach your own user IDs and traits to recorded sessions.

By default, sessions are anonymous. Call `identify()` to attach your own user ID and optional traits to the current session, so you can find a specific user's sessions in the dashboard and connect journeys to real accounts.

## Usage

```ts theme={null}
import { SessionRecorder } from '@web-analytics-ai/obweb';

const recorder = await SessionRecorder.init({
  apiKey: 'ob_live_your_api_key_here',
});

// After your user logs in or is known:
await recorder.identify('user_123', {
  plan: 'pro',
  company: 'Acme Inc',
});
```

Call `identify()` whenever the user becomes known: after login, after signup, or on page load if the user is already authenticated.

## Parameters

| Parameter | Type                  | Description                                                                                         |
| --------- | --------------------- | --------------------------------------------------------------------------------------------------- |
| `userId`  | `string`              | Your identifier for the user, up to 256 characters. Use a stable internal ID, not an email address. |
| `traits`  | `Record<string, any>` | Optional key-value metadata about the user.                                                         |

## How traits are handled

* Trait values are converted to strings before sending. Nested objects arrive as their string representation, so prefer flat, scalar values.
* Empty or non-string keys are dropped.
* Traits are capped at 256KB total. If the cap is reached, remaining traits are dropped and a warning is logged.

## Behavior notes

* `identify()` must be called after `init()` has resolved; it needs the backend session to exist. Called earlier, it logs a warning and does nothing.
* Calling `identify()` again updates the identity on the same session, for example when a user switches accounts.
* Identity applies to the current session. On later visits, call `identify()` again once the user is known.

<Note>
  Traits are visible to your team in the dashboard alongside the session. Do not put secrets or highly sensitive personal data in traits.
</Note>