---
title: Initialization and lifecycle
description: Initialize a managed site and reference every SDK option, readiness, refresh and teardown.
package: "@userreason/js"
version: "0.5.4"
url: https://docs.userreason.com/sdk/initialization/
updated: 2026-10-17
---

# 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](https://docs.userreason.com/sdk/migrate-from-v0-2/index.md) for the required changes to local surveys, response handling and storage.

```ts
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](https://docs.userreason.com/sdk/identity/index.md#restoring-a-signed-in-session). |
| `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](https://docs.userreason.com/sdk/identity/index.md) for assertions and [Targeting](https://docs.userreason.com/prompts/targeting/index.md) 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](https://docs.userreason.com/sdk/storage/index.md). |
| `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](https://docs.userreason.com/sdk/presentation/index.md) 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`.

```ts
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()](https://docs.userreason.com/sdk/identity/index.md#reset-void) on sign-out to establish a fresh anonymous visitor. There is no separate `hide()` method.