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.

Before you start

You need a site ID. Create a site in the dashboard, or let the installation wizard create one and edit your app entry for you:

npx -y @userreason/wizard@latest

1. Install

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

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.

import UserReason from '@userreason/js';

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

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.

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

await UserReason.event('onboarding.completed');

See Events 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:

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:

UserReason.init({ siteId: 'YOUR_SITE_ID', debug: true });

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

Next steps