---
title: Quickstart
description: Install the UserReason SDK, initialize it with your site ID, identify the visitor and report your first event.
package: "@userreason/js"
version: "0.4"
url: https://docs.userreason.com/get-started/quickstart/
updated: 2026-10-10
---

# Quickstart

Add UserReason to a browser app: install the SDK, initialize it with your site ID, identify the visitor and report an event. A published prompt decides who is asked and when.

> **For agents: Using a coding agent?**
>
> Run the wizard, or give your agent this page as Markdown. It is the same content at `/get-started/quickstart/index.md`.

## Before you start

You need a site ID. Create a site in the [dashboard](https://dash.userreason.com), or let the installation wizard create one and edit your app entry for you:

```sh
npx -y @userreason/wizard@latest
```

## 1. Install

The package has no runtime dependencies and ships its own TypeScript types.

```sh
npm install @userreason/js
```

## 2. Initialize

Call `init` once in your browser entry, before the app mounts. In Next.js 15.3 or later, put it in `instrumentation-client.ts`. Importing and calling `init` during server rendering is safe.

```ts title="src/main.ts"
import UserReason from '@userreason/js';

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

> **Note: The site ID is public**
>
> It identifies your site to the SDK. Management credentials never belong in browser code.

## 3. Identify the visitor

After sign-in, connect the visitor to your own account ID. Traits such as the plan can be used to choose an audience. Call `reset()` on sign-out.

```ts title="src/auth.ts"
// After sign-in
UserReason.identify('customer-123', { plan: 'pro' });

// On sign-out
UserReason.reset();
```

## 4. Report an event

Report what happened after your app confirms it succeeded. You report the fact once. The prompt's settings decide the audience, the sampling and the timing.

```ts title="src/onboarding.ts"
await UserReason.event('onboarding.completed');
```

See [Events](https://docs.userreason.com/sdk/events/index.md) for properties, verified events and what is kept.

## 5. Publish a prompt

Write the questions, choose the audience and the trigger, then publish. You can do this in the dashboard, or with the CLI:

```sh
userreason prompt create --workspace WORKSPACE_UUID --site SITE_UUID --file prompt.json --json
userreason prompt publish PROMPT_UUID --workspace WORKSPACE_UUID --site SITE_UUID --revision 1 --json
```

## Check that it works

Set `debug: true` to log each step to the browser console, and listen for errors:

```ts title="src/main.ts"
UserReason.init({ siteId: 'YOUR_SITE_ID', debug: true });

UserReason.on((event) => {
  if (event.type === 'error') console.error(event.error);
});
```

## Next steps

- [Events](https://docs.userreason.com/sdk/events/index.md): Properties, verified events and what is kept.
- [How agents use these docs](https://docs.userreason.com/agents/index.md): Markdown pages, llms.txt, search and the skill.