---
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.

---
title: Events
description: Report something that happened in your app with event(), so a published prompt can decide whether to appear.
package: "@userreason/js"
version: "0.4"
url: https://docs.userreason.com/sdk/events/
updated: 2026-10-10
---

# Events

Report something that happened in your app. UserReason records it and checks whether a published prompt should appear.

## Signature

```ts
UserReason.event(name: string, properties?: Traits, options?: EventOptions): Promise<boolean>
```

## Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | The event name, for example `onboarding.completed`. It starts with a letter or a digit and may contain letters, digits, `.`, `_`, `:` and `-`, up to 160 characters. |
| `properties` | `object` | No | Details of this occurrence, for example `{ format: 'csv' }`. Values are strings, numbers, booleans or `null`. |
| `options.eventProof` | `string` | No | A proof from your backend. It makes the properties of this event verified. |

## Returns

A promise for a boolean: `true` when a prompt was displayed, `false` when none was.

An empty name rejects with a `TypeError`. Any other failure, such as a name in the wrong format or a failed request, resolves to `false` and sends an `error` notification to the listeners you added with `on()`.

## Examples

Report the event after your app confirms the action succeeded.

```ts
await UserReason.event('onboarding.completed');
await UserReason.event('report.exported', { format: 'csv' });
```

Pass an event proof when a prompt depends on a property that must be trusted, such as first use of a feature.

```ts
// result.firstUse and result.eventProof come from your backend.
const result = await runSmartSearch();

await UserReason.event('smart-search.used', { firstUse: result.firstUse }, {
  eventProof: result.eventProof,
});
```

> **Warning: Browser values can be changed by the visitor**
>
> Properties sent without a proof are reported by the browser. Use an event proof from your backend when a prompt depends on them.

## event() or show()

| Method | You want to | What happens |
| - | - | - |
| `event(name, properties?)` | Report that something happened | The event is recorded and matching prompts are checked. A prompt may appear. |
| `show(surveyId)` | Ask for one particular prompt | The named prompt is displayed if display and frequency limits allow it. |

## What is kept

- By default a site captures every event you report. New names appear in the Events tab of the dashboard.
- Individual events are kept for 30 days. Visitor history is kept for 90 days.
- Clicks and page views are not tracked automatically.
- Under Settings, Event capture, a site can capture registered events only.

---
title: How agents use these docs
description: Read any page as Markdown, find pages through llms.txt, search the docs over HTTP, and connect an agent to UserReason.
url: https://docs.userreason.com/agents/
updated: 2026-10-10
---

# How agents use these docs

These docs have one source. A coding agent can read it as Markdown, find pages through `llms.txt` and search it over HTTP. Every route returns the same text as the website.

## Choose a route

| Route | Use it when | Needs |
| - | - | - |
| Markdown page | The agent has web access and already knows which page it needs. | Nothing |
| `llms.txt` | The agent needs to find out which pages exist. | Nothing |
| Search | The agent has a question and needs the section that answers it. | Nothing |
| Agent skill | The agent should know when in-app feedback is worth proposing and how to set it up. | The skill in your project |
| CLI or MCP connector | The agent should create, publish or read things in UserReason. | A grant a person approves |

## Fetch a page as Markdown

Add `index.md` to any page address, or ask for Markdown with a request header. Both return the same file.

```sh
curl https://docs.userreason.com/sdk/events/index.md
curl -H "Accept: text/markdown" https://docs.userreason.com/sdk/events/
```

Each Markdown page opens with its title, the package and version it describes, and its address. The response also carries an `x-markdown-tokens` header with the approximate size of the page in tokens.

## Index files

- [`/llms.txt`](https://docs.userreason.com/llms.txt) lists every page with its address and one line about it.
- [`/llms-full.txt`](https://docs.userreason.com/llms-full.txt) holds the full text of the docs in one file.

## Search the docs

Search returns the matching sections, best first. Each result has a passage, the package and version it applies to, and a link to the exact section.

```sh
curl "https://docs.userreason.com/search?q=report+an+event&limit=1"
```

```json title="Result"
{
  "query": "report an event",
  "results": [
    {
      "title": "Quickstart",
      "heading": "4. Report an event",
      "url": "https://docs.userreason.com/get-started/quickstart/#4-report-an-event",
      "markdown_url": "https://docs.userreason.com/get-started/quickstart/index.md",
      "package": "@userreason/js",
      "version": "0.4",
      "passage": "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. await UserReason.event('onboarding.completed'); See Events for properties, verified…"
    }
  ]
}
```

`limit` is optional. It defaults to 5 and can be at most 20.

## Install the skill

The installation wizard offers to add the UserReason skill to your project, in `.agents/skills/userreason/`. Pass `--agent-skill` to accept the offer without being asked.

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

The skill tells the agent to read these docs instead of relying on what it remembers.

## Connect over MCP

Add the UserReason server to your MCP client. It offers the same scoped management commands as the CLI.

```text title="MCP server address"
https://api.userreason.com/mcp
```

Your MCP client opens a browser window to sign in.

## What needs approval

> **For agents: Reading is open. Changes need a person.**
>
> An agent can read these docs and propose a prompt without signing in. Creating a site, saving a draft, publishing and reading responses each need a grant that a person approves in the dashboard.