> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK reference

> Every method on the Usertick object, with its parameters and behavior.

With the script tag, the API is on `window.Usertick`; with the npm package, it is the default export. The script tag defines `Usertick` before the full runtime loads, and calls made in that time are queued and run in order once it loads.

## init

```ts theme={null}
Usertick.init(options: { site_id: string }): Promise<void>
```

Starts the widget: loads the site's code file with its live surveys, checks each survey's rules and arms the triggers of the surveys that match. Only the npm package needs it, because the script tag starts the widget by itself.

**site\_id** `string` *required*

The site ID from **Settings → Sites**, which is also the file name in the site's install code. The widget shows surveys only on that site's domain and its subdomains.

A second call logs a warning and does nothing. To start again, call [destroy](#destroy) first. Where there is no `window`, as in server rendering, `init` does nothing.

## on / off

```ts theme={null}
Usertick.on(event: string, handler: (data: object) => void): () => void
Usertick.off(event: string, handler: (data: object) => void): void
```

`on` subscribes to a [widget event](https://docs.usertick.com/developers/sdk/events.md) (`open`, `close`, `submit` or `error`) and returns a function that removes the handler. `off` removes a handler. Handlers added before the widget is ready are attached when it becomes ready.

```js theme={null}
const onSubmit = ({ survey_id, answers }) => sendToAnalytics(survey_id, answers);
Usertick.on("submit", onSubmit);
// later
Usertick.off("submit", onSubmit);
```

## trigger

```ts theme={null}
Usertick.trigger(eventName: string, payload?: object): void
```

Sends a custom event. A live survey on the current page whose **Custom event** trigger has the same name opens, if its other rules allow it.

**eventName** `string` *required*

The name the survey's trigger listens for. The match ignores upper and lower case and spaces around the name.

**payload** `object`

The event's properties. A trigger with property rules opens only when every rule holds for them (`plan` is `pro`, `total` is at least `100`), and nested values are reachable with dotted keys such as `order.total`. A key matches exactly first, then in any case. A trigger without rules ignores the payload.

```js theme={null}
Usertick.trigger("checkout_completed", { plan: "pro", total: 249 });
```

The widget keeps the last 50 events. An event sent before the widget is ready is checked against the surveys for 10 seconds after it becomes ready, and a later event for 10 seconds after it was sent, so a survey whose trigger starts a little later, for example after a route change, still sees it. An event that opened a survey never opens that survey again.

## identify

```ts theme={null}
Usertick.identify(
  userId: string | null | undefined,
  traits?: Record<string, string | number | boolean>,
  options?: { hash?: string | null }
): void
```

Tells the widget who the visitor is. On the page, the sign-in state and trait rules in [Targeting](https://docs.usertick.com/surveys/targeting.md#sign-in-state-and-traits) read it, and every survey on the page is checked again at once, so a survey for `plan` is `pro` can open on the same page right after sign-in. When the visitor submits a response, it carries a `respondent` block with the user ID, the traits, the hash and an anonymous ID for this browser. Nothing is sent before Submit, and nothing is sent when the site's **Send user identity with responses** switch is off or the survey has **Anonymous responses** on. See [Identify your users](https://docs.usertick.com/installation/identify.md).

**userId** `string | null | undefined` *required*

Your user ID, up to 256 characters. `null` works like [logout](#logout). `undefined` keeps the stored ID and only updates the traits. An ID different from the stored one starts with no traits and no hash.

**traits** `object`

A flat map of strings, numbers and booleans: up to 50 keys of at most 64 characters, with strings of at most 256 characters. A trait past these limits is dropped with a console warning. Later calls merge into earlier ones. `email`, `name` and `company` become the respondent's email, name and company.

**options.hash** `string | null`

The user hash your server computes, which proves the user ID: the HMAC-SHA256 of the user ID with the organization's identity secret key, as 64 hex characters. It never expires. `null` drops a stored hash, and a value that isn't 64 hex characters is dropped with a console warning. See [Verify your users](https://docs.usertick.com/installation/verify-users.md).

```js theme={null}
Usertick.identify("user_123", { plan: "pro", seats: 12, region: "eu" }, { hash });
```

## logout

```ts theme={null}
Usertick.logout(): void
```

Signals that the user signed out. The widget forgets the ID, the traits and the hash, creates a new anonymous ID and checks every survey again. The next response carries only the new anonymous ID, so the next person on a shared device is never merged into this user. The display history is kept, so a survey that was already answered doesn't come back. While nobody is signed in, `logout()` keeps the anonymous ID, so the call is safe on every anonymous page load.

## show / hide

```ts theme={null}
Usertick.show(): void
Usertick.hide(): void
```

`show` opens a survey without waiting for its trigger. It brings back the popup on screen or minimized, or else opens the side button's survey. Otherwise, it opens the highest-priority survey that passes every other rule on the page, including the repeat behavior, and logs a console message when none does. `hide` closes the open popup; with no popup open, it hides the minimized popup or the side button. Embedded surveys stay on the page. `show` is the usual way to test a survey without waiting for its trigger.

## reset

```ts theme={null}
Usertick.reset(): void
```

Clears what the widget remembers in this browser: the display history (cooldowns, shown-once and submitted flags), the visit counters, the anonymous ID and the `identify` record with its hash. Responses waiting to be sent are kept. Use it while testing a survey that doesn't appear again; to sign a user out, use [logout](#logout).

```js theme={null}
Usertick.reset();
location.reload();
```

## destroy

```ts theme={null}
Usertick.destroy(): void
```

Removes every survey card, listener and queued custom event from the page. A later `init` starts fresh, so handlers added with `on` need to be added again. In a single page app, call it from the cleanup of the component that called `init`.

## Survey selection

Every live survey that passes its page rules, devices, targeting and repeat behavior arms its trigger. The first popup trigger to fire opens its survey, and the other popups wait. Only one popup shows at a time. After it closes, the others are armed again and can still open under their own trigger and repeat behavior. A side button and an embedded survey take places of their own, so they never hold a popup back. Surveys are checked again after a route change in a single page app and after `identify`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.