Identity resolution

OakData tracks people across the anonymous-to-known boundary. A visitor is followed anonymously from their very first pageview; when they sign in, their earlier activity is stitched to the identified profile so you see one continuous history — including everything they did before they had an account.

The two ids

• anonymous_id— a random id generated on first visit and stored in the browser. It follows the visitor while they're unknown.
• distinct_id — the visitor's canonical id. Before identify it equals the anonymous id; after, it becomes the user id you supplied.

identify: anonymous → known

Call identify once you know who the visitor is — typically right after sign-in or sign-up. It emits an $identify event carrying both the new user id and the previous anonymous id, which is the link the server uses to merge the two histories.

oak.identify(user.id, { email: user.email, name: user.name })

From then on oak.getDistinctId() returns the user id, and new events are attributed to the identified person.

Traits

Traits are durable attributes of a person — email, plan, role. Set them with identify (as the second argument) or directly with set and setOnce. The server replays $identify, $set, and $set_once events chronologically to compute the visitor's current traits, so a profile always reflects the latest values (with setOnce never overwriting an existing key).

oak.set({ plan: 'enterprise' })          // overwrites
oak.setOnce({ signup_source: 'docs' })   // only if not already set

Groups

A group ties a person to an account, company, or workspace — an entity many users share. Group membership and group traits are resolved the same way traits are, and surface on the visitor profile.

oak.group('company', 'acme-co', { name: 'Acme', plan: 'enterprise' })

alias: merging ids you control

aliaslinks the current distinct id to another id you own. Reach for it when you mint an id on your backend and need to tie it to the browser's anonymous id, in cases identifyalone doesn't cover.

reset: ending a session of identity

On sign-out, call oak.reset(). It clears the stored ids, traits, super properties, and groups, then issues a brand-new anonymous id — so the next person on a shared device starts clean and isn't merged into the previous user.

Looking someone up

The visitor endpoint (and the get_visitor MCP tool) accept either the distinct id or the anonymous id, returning the resolved profile: user id, accumulated traits, groups, attribution, the identity timeline, and recent sessions.