How to identify users with the JustOneCX SDK

By Hasan · November 5, 2026 · 5 min read

To identify users with the JustOneCX SDK, call identify(userId, traits) after the user signs in, group(accountId, traits) to set their account, and reset() when they sign out. Traits are properties such as plan or role that merge into the profile. Add a userHash from your server so nobody can claim another person's id.

What does identify() do?

identify() tells JustOneCX who the current user is.

identify("user-42", { role: "admin", plan: "growth" });

Traits merge into what the user already has. Call it on every page load after login, not only on the login event, to keep traits fresh. The order relative to init() does not matter. A call made before init() is queued and runs when init() does.

The signature is:

function identify(userId: string, traits?: Traits, options?: { userHash?: string }): Promise<void>;

The promise resolves when the backend has saved the traits. It never rejects. If you need targeted tours to appear straight away, await it and then call init() again. Traits must be saved before targeting can match them.

When should you call group()?

Call group() to set the account, company, team or organisation the user belongs to.

group("acme-inc", { plan: "growth", seats: 12 });

The signature is:

function group(accountId: string, traits?: Traits, options?: { accountHash?: string }): Promise<void>;

accountHash is the HMAC signature of accountId, computed the same way as userHash. Call group() right after identify() for products where people work in shared accounts. This lets you read analytics and votes by account.

What are traits?

Traits are key and value pairs about a person or an account. Examples are role, plan and seats. Use them for targeting and for reading your data. Keep trait names stable. Changing plan to tier later splits your data.

Do not put secrets or unstructured personal notes in traits. Send only what you need for targeting and analysis. To see how audiences use traits, read the user segmentation article.

When should you call reset()?

Call reset() when the user signs out.

import { reset } from "@justonecx/sdk";

await reset();                    // clear identity, start a new anonymous visitor, run init() again
await reset({ remount: false });  // clear only, do not run init() again

The visitor id is a permanent id in localStorage. On a shared browser, the next person who signs in would otherwise inherit the previous person's open chat and other visitor state. reset() removes the chat bubble, stops any tour still playing, deletes the stored visitor id and creates a new one. Then it runs init() again unless you pass remount: false. A new chat bubble appears after reset(). This is by design.

What is userHash and why use it?

Your Public key is in your page source, so anyone can read it. Without more protection, any page that has it can call identify("someone-else"). The identify() call alone is not proof of identity.

Identity verification closes that gap. After sign-in, your server signs the user id with the Secret key. The SDK sends the result as userHash.

import { createHmac } from "node:crypto";

const userHash = createHmac("sha256", process.env.JUSTONECX_SECRET_KEY)
  .update(String(user.id))
  .digest("hex");

Then pass it in the browser:

identify(user.id, { plan: user.plan }, { userHash });
group(account.id, { plan: account.plan }, { accountHash });

Sign exactly the same string you pass to identify(). A number in one place and a string in the other gives a rejected hash.

The Secret key stays in your server environment as JUSTONECX_SECRET_KEY. Never compute the hash in the browser. Turn on Require identity verification in Settings → Developers → Identity verification only after your live site sends userHash. If you turn it on first, all your existing users count as unverified. See identity verification and the post on securing identify with a user hash.

When verification is on and you do not pass userHash, the call is rejected and the SDK logs identify() was rejected in the browser console.

What is the single-page app gotcha?

In a single-page app the browser does not reload when the route changes. The SDK then does not fetch content for the new page. Tours and announcements do not change when the page changes.

Pass trackRouteChanges: true to init():

import { init } from "@justonecx/sdk";

await init({
  publicKey: "pk_your_workspace_key",
  apiUrl: "https://api.justonecx.com",
  trackRouteChanges: true,
});

With the script tag, use data-track-route-changes="true". Leave it off if you already call init() from your router. Calling init() again is safe. A tour or announcement already on screen is not shown a second time.

Also call init() in the browser only. In a framework, call init() in your top-level component and identify() in an effect that runs after it. If you see identify() called before init(), that order is the cause. If a tour still does not appear, see product tour not showing.

Does one person on two devices count once?

The visitor id is per browser. If the same user calls identify("user-42") from two devices, JustOneCX links both to the same person for analytics and targeting. Chat is the exception. A conversation stays with the browser that started it, so a claimed identity cannot read another person's chat history.

Frequently asked questions

Should I call identify() only at login?

No. Call it on every page load after login to keep traits fresh.

Does the order of init() and identify() matter?

No. An identify() call made before init() is queued and runs when init() does.

What happens to a call without a valid hash?

When verification is on, the call returns normally but is ignored. It cannot merge into another person's profile or change their traits.

Where do I find the full API?

See the identify, group, track reference.

See how it works in the live demo.

See it working in 2 minutes

Try the live demo

Related