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

# identify()

> Associate all future events with a specific user ID.

## Overview

`identify()` links all future `track()` calls to a specific user. Call this **after a user logs in**. This lets you see which events belong to which user on your dashboard.

<Note>
  **React / Next.js users:** If you are using the `useAnalytiq()` hook and passing `userId: user?.id`, you **do not need to call `identify()` manually**. The hook calls it automatically whenever your `userId` changes. You only need `identify()` if you are using Vue, Vanilla JS, or another non-React framework.
</Note>

## Signature

```ts theme={null}
identify(userId: string): void
```

## Parameters

| Parameter | Type     | Required | Description                                                                              |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------- |
| `userId`  | `string` | Yes      | A unique identifier for the user. Can be their database ID, email, or any unique string. |

## Example

```js theme={null}
import { identify } from 'analytiq'

// Best: use a clean, human-readable ID from your auth system
identify('user_abc123')

// OK: use their email address
identify('bhavishaya@gmail.com')

// OK: use their database ID from response.data.user.id
identify(user.id)
```

<Warning>
  **Avoid using raw MongoDB `_id` directly** (e.g. `"67a3b2c1d4e5f6789012345"`). These ObjectId strings look unreadable on the dashboard. Use a cleaner identifier — like their email or a `user.id` field from your auth API response — so user journeys are easy to read on the dashboard.
</Warning>

## When to call it

<Tabs>
  <Tab title="React / Next.js">
    If using the `useAnalytiq()` hook, **you don't need to call `identify()`**. Just update your authentication state, and the hook handles it.

    ```js theme={null}
    // React example
    async function handleLogin(email, password) {
      const response = await api.post('/auth/login', { email, password })
      const user = response.data.user

      // Just save the user to your state/context.
      // The useAnalytiq({ userId: user.id }) hook will see the change
      // and call identify() automatically.
      setUser(user)

      navigate('/dashboard')
    }
    ```
  </Tab>

  <Tab title="Vue / Vanilla JS">
    Call `identify()` immediately after a successful login:

    ```js theme={null}
    // Vue / Vanilla example
    async function handleLogin(email, password) {
      const response = await api.post('/auth/login', { email, password })
      const user = response.data.user

      identify(user.id)   // call here, right after login

      navigate('/dashboard')
    }
    ```
  </Tab>
</Tabs>

## What happens after identify()

Every `track()` call after `identify()` will automatically include the `userId`:

```js theme={null}
identify('user_abc123')

track('page_view', { page: 'Dashboard' })
// Event sent with userId: 'user_abc123' attached automatically
```

## Important rules

<Warning>
  **Funnels and Retention require `identify()`.**

  The Funnel and Retention engines only count events linked to a user. If you never call `identify()`, events are stored with `userId: null` and **Funnels will show 0 users in every step** and Retention cohorts will be empty. Always call `identify(user.id)` right after login.
</Warning>

<Note>
  If you don't call `identify()`, events are still tracked — they just won't be linked to a specific user. This is fine for anonymous visitor tracking on the Overview and Events pages only.
</Note>

* Call `identify()` once per session, right after login
* The identity persists until `reset()` is called
* You can call `identify()` again with a different ID to switch users (rare case)

## Reset identity on logout

When the user logs out, call `reset()` to clear their identity:

```js theme={null}
import { reset } from 'analytiq'

function onLogout() {
  reset()  // clears userId so future events are anonymous again
}
```

This is important — without calling `reset()`, the next user to log in on the same browser session would have their events attributed to the previous user.