> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpalive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# identify(): tie events to users and tenants
> Call HelpAlive.identify() after login to tie events to real users and tenants. userId and tenantId are required; traits power segmentation and personalization.
`identify()` is the only call you have to make beyond the script tag. It tells HelpAlive which user is using your product, which workspace they belong to, and what traits to use for segmentation and personalization.
## When to call it
Call `identify()` once per session, right after the user logs in. Common places to put it:
* Your login callback.
* The first authenticated page or layout that loads after sign-in.
* Anywhere the user object becomes available on the client.
If `identify()` runs before the script has finished loading, the call is queued and replayed automatically — you don't need to add any extra checks.
## Signature
```typescript theme={null}
HelpAlive.identify({
userId: string; // required — your stable app user ID
tenantId: string; // required — workspace/org ID, or "default"
tenantName?: string;
displayName?:string;
email?: string;
role?: string;
plan?: string;
createdAt?: string; // when the user signed up
});
```
## Field reference
| Field | Required | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `userId` | Yes | Your app's stable user ID. Must not change across sessions. Avoid using email if it can change. |
| `tenantId` | Yes | Workspace or organization ID. If your app doesn't have multi-tenancy, pass `"default"`. |
| `tenantName` | No | Display name for the workspace. Shown in **Insight → Audience** in your dashboard instead of the raw ID. |
| `displayName` | No | Full name of the user (e.g. `"Priya Sharma"`). Recommend `firstName + " " + lastName`. |
| `email` | No | User's email. Used for display and search. Keep `userId` as the stable identifier. |
| `role` | No | User's role or permission level (e.g. `"admin"`, `"editor"`, `"viewer"`). Helps segment behavior. |
| `plan` | No | Subscription tier (e.g. `"free"`, `"pro"`, `"enterprise"`). Enables plan-segmented insights and chatbot behavior. |
| `createdAt` | No | When the user signed up. Helps the AI assistant tailor its tone for new vs. seasoned users. |
## Why identify() matters
Until you call `identify()`, HelpAlive doesn't record any activity for that user. Once you call it, HelpAlive can:
* **Connect activity to real users** across sessions and devices.
* **Group users by workspace** so your dashboard reflects the way you actually think about customers.
* **Personalize the AI assistant's greetings and suggestions** based on the user's plan, role, and recent activity.
* **Show per-user profiles** in your dashboard so you can see what any individual customer has been doing.
## Example
```javascript theme={null}
HelpAlive.identify({
userId: "user_8x92k",
tenantId: "acme-corp",
tenantName: "Acme Corp",
displayName: "Priya Sharma",
email: "priya@acme.com",
role: "admin",
plan: "pro",
createdAt: "2024-11-03T09:00:00Z"
});
```
## Apps without workspaces
If your product has one user per account and no concept of workspaces, pass a fixed value for `tenantId`:
```javascript theme={null}
HelpAlive.identify({
userId: "user_8x92k",
tenantId: "default"
});
```
You can switch to real workspace IDs later. Existing activity and profiles will be re-grouped automatically.
## Workspace switching mid-session
If a user switches workspaces without reloading the page (common in B2B apps with a workspace switcher), call `identify()` again with the new `tenantId`. HelpAlive will start recording their activity under the new workspace from that point on.
```javascript theme={null}
// User clicks "Switch to Beta Inc."
HelpAlive.identify({
userId: "user_8x92k",
tenantId: "beta-inc",
tenantName: "Beta Inc."
});
```
## Logout
When the user logs out, the SDK clears identity automatically when the session ends. If your app doesn't fully reload between users (a shared device, for example), you can clear it manually with `HelpAlive.reset()` to prevent the next user inheriting the previous identity. For most apps, this isn't needed.
## Anonymous sessions
If you never call `identify()`, HelpAlive doesn't record any activity for that user. Anonymous browsing isn't stored — by design. This keeps your analytics clean and keeps unauthenticated traffic out of the AI assistant.
## Things to know
Use your database ID, a UUID, or any other ID that doesn't change. Don't use email — if a user changes their email later, their activity will end up under two separate profiles.
`email` makes the user searchable in your dashboard, but HelpAlive uses `userId` to recognize them. Always send a stable `userId`.
Pass `"default"` if your app has no concept of workspaces. HelpAlive groups activity by workspace, so a value is required even if you only have one.
Safe and expected. Each call updates the user's identity. Identical calls don't create duplicates.
These two fields are stored on the user profile so your team can search and support. They never appear in raw activity records, and the user can be deleted on request.
## Next steps
Pause tracking until your cookie banner returns a decision.
Train the AI assistant on your docs.