Events
Report something that happened in your app. UserReason records it and checks whether a published prompt should appear.
Signature
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.
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.
// 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,
});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.