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.

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.

Signature

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

import { identify } from 'analytiq'

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

// OK: use their email address
identify('[e-mail]')

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

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.

When to call it

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.

// 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')
}

Vue / Vanilla JS

Call identify() immediately after a successful login:

// 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')
}

What happens after identify()

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

identify('user_abc123')

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

Important rules

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.

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.

• 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:

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.