∧pex

Identity

Associate tracked events with known users and stitch anonymous visitor sessions to real identities.

identify()

Call identify() when you learn who a visitor is — at login, signup, or form submission. All subsequent track() calls are attributed to this user.

import { identify } from "@apex-inc/sdk";

identify("user_8x92k", { email: "jane@acme.co", plan: "pro" });
ParameterTypeDescription
userIdrequiredstringA unique identifier for the user. Can be a database ID, email address, or any stable identifier.
traitsRecord<string, unknown>Key-value pairs describing the user — email, name, plan, company, etc.

Identity Stitching

When the userId looks like an email address (contains @), the SDK automatically calls POST /api/identity/stitch to merge the anonymous visitor session with the known user profile. This also triggers if traits.email is set.

This means every event the visitor triggered before identifying themselves — pageviews, clicks, experiment exposures — gets linked to the real user.

Info

Identity stitching is automatic. You don't need to call a separate API. Just pass an email as the userId, or include email in the traits object.

Anonymous → Known User Flow

Here's the typical lifecycle:

  1. Visitor lands on your site — Apex assigns an anonymous visitor ID via the tracking snippet or SDK
  2. Visitor browses pages — track("page_view", ...) calls are recorded under the anonymous ID
  3. Visitor submits a form or logs in — you call identify("jane@acme.co")
  4. Apex stitches — all prior anonymous events are now attributed to jane@acme.co
  5. Future events — every track() call automatically includes the identified user

Examples

At Login

async function onLogin(credentials) {
  const user = await api.login(credentials);

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

At Signup

async function onSignup(formData) {
  const user = await api.createAccount(formData);

  identify(user.email, {
    name: formData.name,
    company: formData.company,
    source: "signup",
  });
}

With trackForm()

The trackForm() helper calls identify() automatically, so a single call handles both the event and the identity:

import { trackForm } from "@apex-inc/sdk";

trackForm({
  email: "jane@acme.co",
  formId: "contact-us",
  fields: { message: "Interested in the enterprise plan" },
});

Warning

Call init() before identify(). If the SDK isn't initialized, the call is ignored and a warning is logged to the console.

Tip

You can call identify() multiple times. The SDK uses the most recent userId. Traits are sent with each call, so include any updated values.

Next Steps

PreviousTracking EventsNextGetting Started