Identify users

identifyUser, setUserProperty, logout — how identity attaches to sessions and Visitors.

When to call identify

After login (or whenever you know who the person is). Call again when traits change (plan, name, email).

API

The shipped signature accepts either a bare traits object or { userProperties }:

// Bare properties (common)
await tracker.identifyUser({
  email: "ada@example.com",
  name: "Ada Lovelace",
  plan: "pro",
});

// React-wrapper shape
await tracker.identifyUser({
  userProperties: {
    email: "ada@example.com",
    name: "Ada Lovelace",
  },
});

Detail	Behavior
Return value	`Promise<string>` — the current session’s anonymous `endUserId`
Mid-session id switch	The anonymous id for the current session is kept; if the server finds an existing user, the canonical id is persisted for future sessions
Transport	`POST /api/ingestion/user` with `Authorization: Bearer <apiKey>`
Local cache	Traits merge into tracker + `PropertyManager`

There is no identifyUser(userId, traits) two-argument form in the current SDK. Pass identifying traits (commonly email) inside the properties object; the server associates / creates the end user.

Incremental traits

tracker.setUserProperty("plan", "enterprise");

getUserAttributes() returns the merged local + PropertyManager traits.

What changes in the product

Surface	Effect
Visitors / Users	Rows gain email / name / traits
Session filters	“User” filters become useful
Issues	Affected-user counts become meaningful when identity is present
Replay headers	Known-user labels when traits include name/email

Logout / shared devices

tracker.logout();

logout() (browser only):

Clears the human_behavior_end_user_id cookie / localStorage entry
Clears session storage for the active session key
Resets in-memory user properties
Mints a new anonymous endUserId and new sessionId / windowId
Takes a FullSnapshot so the new window can be replayed

Call this when the user signs out of your app so the next person on a shared browser is not merged into the previous identity.

Persistence notes

Storage key	Purpose
`human_behavior_end_user_id`	Cookie + localStorage anonymous / canonical user id (365-day cookie)
`human_behavior_session`	Session continuity across reloads within the idle window

Visitors
Privacy
Ingestion API (POST /api/ingestion/user)