Identify Users

Call identify after sign-in to link the anonymous visitor to a stable external user ID and optional profile data.

Identify a UserCopy Anchor Link

import { useIdentify } from "@faststats/react";

const identify = useIdentify();
await identify("user_123", "ada@example.com", {
	name: "Ada Lovelace",
	traits: { plan: "pro" },
});

const { $faststats } = useNuxtApp();

// The client only exists in the browser, so call it from onMounted or an
// event handler rather than during server rendering.
onMounted(async () => {
	await $faststats.identify("user_123", "ada@example.com", {
		name: "Ada Lovelace",
		traits: { plan: "pro" },
	});
});

import { identify } from "@faststats/web";

await identify("user_123", "ada@example.com", {
	name: "Ada Lovelace",
	traits: { plan: "pro" },
});

The external ID is required. Email and all profile fields are optional. You can also pass one object instead of positional arguments.

await identify({
	id: "user_123",
	email: "ada@example.com",
	name: "Ada Lovelace",
	traits: { plan: "pro" },
});

Calling identify on every page load is fine. If the payload is identical to the last one sent in this browser session for the same visitor, and no trait changes are queued, it resolves true without a request. Pass force: true to always send.

Profile OptionsCopy Anchor Link

traits overwrite values the person already has. traitsOnce only fill in keys the person does not have yet, which suits first-touch data that should never change after it is recorded.

await identify("user_123", "ada@example.com", {
	traits: { plan: "free" },
	traitsOnce: { signupSource: "reddit", signedUpAt: "2026-10-27" },
});

Update TraitsCopy Anchor Link

Use setTraits to change traits on the identified user without calling identify again, for example after a plan upgrade.

import { useSetTraits } from "@faststats/react";

const setTraits = useSetTraits();

async function onUpgrade(plan: string) {
	await upgradeSubscription(plan);
	await setTraits({ plan, upgradedAt: new Date().toISOString() });
}

const { $faststats } = useNuxtApp();

// Call from an event handler or onMounted, never during server rendering.
async function onUpgrade() {
	await $faststats.setTraits({ plan: "pro" });
}

import { setTraits } from "@faststats/web";

await setTraits({ plan: "pro" });

New keys are added and existing keys are overwritten. Traits you do not pass are left untouched.

Set OnceCopy Anchor Link

Pass { mode: "setOnce" } to only set keys the person does not have yet. Later calls never overwrite the first value, so you can call it on every visit to an onboarding step and still keep where the user originally came from.

import { setTraits } from "@faststats/web";

const params = new URLSearchParams(location.search);

await setTraits(
	{
		signupSource: params.get("utm_source") ?? "direct",
		firstLandingPage: location.pathname,
	},
	{ mode: "setOnce" },
);

Remove TraitsCopy Anchor Link

unsetTraits removes traits by key.

import { unsetTraits } from "@faststats/web";

await unsetTraits(["trialEndsAt", "legacyPlan"]);

In Nuxt call $faststats.unsetTraits(). In React, get the instance with useAnalytics() and call analytics?.unsetTraits().

Before IdentifyCopy Anchor Link

If the visitor has not been identified yet, setTraits and unsetTraits keep the change in memory and send it, in order, right after the next successful identify call. The queue only lives for the current page, or the current session of a single-page app: a full page load or reload discards it, and logout clears it. Use it for changes that happen on the same page as sign-in, such as a sign-up form that creates the account and identifies the user without navigating away.

import { identify, setTraits } from "@faststats/web";

// In the sign-up form, before the account exists
await setTraits({ signupSource: "newsletter" }, { mode: "setOnce" });

// On the same page, once the account is created. The queued trait is sent
// right after this call succeeds.
await identify("user_123", "ada@example.com", { traits: { plan: "free" } });

Queued changes are applied after the identify request, so for the same key they win over the traits passed to identify itself. Once identify has been called, setTraits and unsetTraits apply to that user right away, even while its request is still in flight.

Return ValueCopy Anchor Link

identify resolves to true when the request was sent, or skipped because the same identify was already sent in this session. It returns false if the client is not active, consent is denied, cookieless mode is active, or the external ID is empty.

setTraits and unsetTraits resolve to true once the change is sent for the identified user. They resolve to false when the change was queued for the next identify, when the request fails, or when the client is not active, consent is denied, or cookieless mode is active.

What Is Stored and SentCopy Anchor Link

When you call identify, the SDK stores the external ID in localStorage next to the anonymous visitor ID, scoped to your site key, and restores the previous value if the request fails. It is then sent as externalId with every analytics event, error, and session replay chunk. Web Vitals reports do not include it. Events are attributed to the person right away, and activity from the same user on different devices ends up on one profile.

logout always removes the stored ID, whatever the consent mode, and so does setting consent to "denied".

Read the stored ID with getExternalId() on the client instance. It returns an empty string before identify, in cookieless mode, and when consent is denied.

import { init } from "@faststats/web";

const analytics = init({ siteKey: "your_site_key" });
const userId = analytics.getExternalId();

In React the instance comes from useAnalytics(); in Nuxt it is $faststats.

Cookieless ModeCopy Anchor Link

In cookieless mode (cookieless: true or consent set to "anonymous"), the external ID is never stored or sent. identify, setTraits, and unsetTraits send nothing and resolve to false.

Log OutCopy Anchor Link

Call logout after sign-out. It forgets the stored external ID, drops any queued trait changes, rotates the session, and by default resets the anonymous identifier. The external ID is removed even when consent is denied or cookieless mode is active, so the next person on a shared device is never attributed to the previous user.

import { logout } from "@faststats/web";

logout();

Pass false to keep the anonymous identifier and only clear the external ID and reset the session. In React use useLogout; in Nuxt call $faststats.logout().