Use identify() to associate the browser SDK with a known person in your application. Use a stable internal ID, and send only the profile fields needed for your use case.

Identify a signed-in user

Initialize Userorbit once in the browser, then identify the person after your application's authentication has resolved:

import userorbit from "userorbit-js";

await userorbit.init({ accountId: "YOUR_ACCOUNT_ID" });

await userorbit.identify("usr_demo_1042", {
  attributes: {
    plan: "business",
    role: "editor",
  },
});
JavaScript

Replace the example ID and values with your application data. identify() accepts a non-empty string or a number; numeric IDs are converted to strings. Keep the ID consistent across sessions. Avoid email addresses, names, and changing display names as identifiers.

Email and name are optional:

await userorbit.identify("usr_demo_1042", {
  email: "person@example.com",
  name: "Avery Chen",
  attributes: { plan: "business" },
});
JavaScript

Omit these fields when an opaque ID is enough. Pseudonymous IDs still represent people and do not make the collected activity anonymous.

Identify during initialization

When authentication is already resolved, the first init() call may include userId, email, name, and attributes:

await userorbit.init({
  accountId: "YOUR_ACCOUNT_ID",
  userId: "usr_demo_1042",
  attributes: { plan: "business" },
});
JavaScript

For authentication changes after initialization, use identify(). Repeating init() after the runtime has initialized is not a way to update identity.

Update profile fields

Use setEmail() to update email and setAttribute() for a custom attribute:

await userorbit.setEmail("person@example.com");
await userorbit.setAttribute("plan", "enterprise");
JavaScript

You can also call identify() again with updated attributes. Supplied attributes are merged with existing configuration. Omitting an old attribute is not a request to delete it.

For an application with multiple customer accounts, describe the active account with custom attributes:

await userorbit.identify("usr_demo_1042", {
  attributes: {
    "account.id": "acct_demo_12",
    "account.plan": "business",
  },
});
JavaScript

These are ordinary person attributes. The browser SDK does not expose a separate company or group identification method. Re-identify with updated values after a tenant switch, and verify targeting with a test contact.

Understand logout and reset

Call logout() when the known person signs out:

await userorbit.logout();
JavaScript

This clears the SDK configuration and stops the current analytics client. It does not erase the persisted browser distinct ID, guarantee that an active replay stops, or delete data already received by Userorbit. A later initialization without an explicit identity can reuse that stored ID.

reset() refreshes the SDK using its current person ID and attributes. It is not an anonymous-identity reset, a data-deletion command, or a way to isolate the next person on a shared device.

Before enabling Userorbit on shared-browser sign-in flows, test sign-out, reload, and a second person's sign-in. Identify the new person explicitly and confirm that their activity and profile are separate. If your requirement is to return to an unlinked anonymous visitor after sign-out, confirm a supported implementation with Userorbit before deploying it. Include active recording behavior in that review; logout() and reset() are not consent-withdrawal controls.

Verify identity

  1. Use a dedicated test account and the intended Userorbit workspace.
  2. Open Contacts and find the expected user ID.
  3. Check only the profile fields you intended to send.
  4. Open Analytics → Live Events in the correct project and inspect a test event's identity.
  5. Repeat after tenant switching and sign-out.

An SDK method returning does not prove that the server received the update. Check the outcome in Userorbit and review browser Network errors if it is missing.

Read Protect personal data with pseudonymous IDs and replay masking for privacy boundaries and validation guidance.

Was this helpful?