Identity and traits

The SDK starts anonymously by default. Identify the visitor after your application's authentication succeeds so targeting and responses can be associated with your account ID.

Restoring a signed-in session

When authentication is asynchronous, set waitForIdentity: true in your browser entry. The SDK waits for your application's current account before opening its first session or evaluating page-load surveys. The server can then exclude surveys that account already completed, without briefly displaying an anonymous survey.

import UserReason from '@userreason/js';

UserReason.init({ siteId: 'YOUR_SITE_ID', waitForIdentity: true });

// In your application's successful authentication callback:
UserReason.identify('customer-123', { plan: 'pro' });
await UserReason.ready();

Resolve authentication before awaiting ready(), event(), show() or refresh(); these calls also wait for identity. reset() cancels pending work and waits for the next identify() too, so sign-out and expired-login recovery cannot show an anonymous survey. An authentication failure leaves prompting paused until your app identifies. There is no timeout or automatic reuse of a previously signed-in account. The option defaults to false for sites that should survey immediately as anonymous.

identify(userId, traits?, identityToken?): void

import UserReason from '@userreason/js';

UserReason.identify('customer-123', { plan: 'pro', teamSize: 8 });
await UserReason.ready();

In managed mode, trait keys follow the event-name identifier format, with at most 128 keys and 4000 characters per string value.

The first identify() call connects the anonymous visitor to the account while preserving any open survey, typed answers, voice recording and pending submission. Calling identify() again for the same ID merges new traits and also preserves the survey. Switching between identified accounts replaces the traits, closes the current survey and starts a session for the new account. identify() itself returns immediately; await ready() when subsequent work needs the updated session.

An open survey retains the session that admitted it for display, dictation and response requests. The server links its anonymous feedback to the identified person without changing the original evidence or upgrading its verification. Later events and surveys use the identified session. Use waitForIdentity when the first survey must respect a returning account's history; preserving an already admitted anonymous survey cannot retroactively check that history before display.

Verified identity

A browser account ID is attribution, not proof that the visitor owns that account. Browser traits such as plan are also unverified. Use verified_trait audience conditions when eligibility must depend on trusted data.

Your authenticated backend must derive the account ID and trusted traits from its own session and data, then obtain a short-lived UserReason identity assertion with permission for that site. The management identity operation returns identity_token and expires_in (60 seconds). Send only the assertion to the browser; keep management credentials on your server.

Pass the assertion as the third argument to identify(), or configure getIdentityToken at initialization to obtain a fresh one when the SDK creates or renews its session. The callback may be asynchronous. A token supplied once through identityToken is not a permanent credential.

An identity assertion verifies identity and traits. Event proofs verify a particular occurrence and its properties.

reset(): void

Call after sign-out:

import UserReason from '@userreason/js';

UserReason.reset();
await UserReason.ready();

This closes the survey, aborts pending work, and clears the stored session, event summaries and traits. By default it starts a fresh anonymous visitor. With waitForIdentity: true, it waits for the next identify() instead. It does not restore a previous anonymous identity or delete responses and frequency history held on the server.

Use identify() when switching directly between signed-in accounts. Use destroy() when tearing down the whole integration.