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