Initialization and lifecycle

The default export is one shared SDK instance. Initialize it once in your browser entry and reuse it throughout the app.

Moving from SDK 0.2? Read Upgrade from SDK 0.2 for the required changes to local surveys, response handling and storage.

import UserReason from '@userreason/js';

UserReason.init({ siteId: 'YOUR_SITE_ID' });
await UserReason.ready();

Replace the placeholder with the UUID from your site. The package includes its public TypeScript types. If an integration needs an independent instance, import the named UserReason class and construct it with new UserReason().

init(options): this

init() validates its options and starts loading published configuration and a visitor session. Repeating it on an initialized instance is a no-op, so a later init({ debug: true }) does not change existing options. On the server, valid initialization is inert.

Connection and targeting options

Option	Default	Meaning
`siteId`	Required	Public site UUID. Determines the workspace and published surveys.
`workspaceId`	Resolved from the site	Optional workspace UUID; when given, the site must belong to it.
`apiBaseUrl`	`https://api.userreason.com`	HTTPS origin, with no path, query or credentials. Loopback HTTP is allowed for local development.
`debug`	`false`	Log lifecycle and request status, excluding visitor values and tokens.
`configRefreshMs`	`60000`	Configuration revalidation interval, from `10000` to `86400000` milliseconds.
`automaticTriggers`	`true`	Observe configured page-load, route, selector, delay and scroll triggers. Explicit `event()` and `show()` remain available when false.
`waitForIdentity`	`false`	Wait for `identify()` before creating a session or prompting. `reset()` waits for the next identity too. See Identity.
`identityToken`	Unset	Short-lived backend assertion used to verify identity.
`getIdentityToken`	Unset	Function returning a fresh token, or a promise for one, during session creation or renewal. May return `undefined`.
`appVersion`	Unset	Your app's version, recorded with displays; 1–64 characters.
`requestTimeoutMs`	`8000`	Request timeout in milliseconds; a finite, nonnegative number.

See Identity for assertions and Targeting for trigger and frequency behavior. Automatic refresh can pause while the page is hidden and no survey is open.

Storage and interface options

Option	Default	Meaning
`storage`	`'local'`	`'memory'`, `'local'` or `'cookie'`; see Storage and consent.
`cookieDomain`	Current host	Optional domain such as `.example.com` for cookie visitor storage.
`locale`	Visitor language for managed surveys	Language tag such as `nl` or `pt-BR`.
`messages`	Built-in interface text	Partial `Messages` object; each override is at most 500 characters.
`theme`	Built-in theme	Optional `accent`, `background`, `text` and `fontFamily` strings.
`closeOnBackdropClick`	`false`	Allow outside-click dismissal; unfinished answers require confirmation.
`nonce`	Unset	Your CSP nonce for nonce-based style insertion.

See Appearance and language for examples. Every survey is published from the dashboard, CLI or MCP: the SDK takes no survey definitions and has no custom response transport. The surveys, endpoint and submit options of earlier versions are gone.

ready(): Promise<void>

Waits for remote configuration and the visitor session. Use it to check initialization, or after changing identity. It rejects on a loading failure. Resolving means the integration is connected; it does not imply an eligible survey exists. Before initialization, and outside the browser, it resolves without any request.

With waitForIdentity: true, it also waits for the application's identity resolution. Call identify() independently of ready() to avoid waiting on your own authentication callback. Reset or destruction cancels an unresolved startup and rejects its pending calls.

refresh(): Promise<void>

Revalidates published configuration and private targeting context. Use it after publishing when you need the current configuration immediately. It can reject; automatic revalidation also runs according to configRefreshMs.

import UserReason from '@userreason/js';

try {
  await UserReason.refresh();
} catch (error) {
  console.error('Could not refresh UserReason', error);
}

destroy(): void

Closes the widget, aborts pending work, stops observers and refresh timers, removes listeners, and clears the instance's in-memory identity and options. The stored visitor and session remain. You can initialize the instance again afterward.

Use reset() on sign-out to establish a fresh anonymous visitor. There is no separate hide() method.