SDK notifications

Use on() to observe the SDK lifecycle. These notifications are separate from the application events your app reports.

on(listener): unsubscribe

Register listeners before initialization if you need to observe startup errors. The returned function removes that listener.

import UserReason from '@userreason/js';

const unsubscribe = UserReason.on((notification) => {
  switch (notification.type) {
    case 'shown':
    case 'dismissed':
      console.info(notification.type, notification.surveyId);
      break;
    case 'submitted':
      console.info('Response accepted', notification.response.responseId);
      break;
    case 'error':
      console.error(notification.error);
      break;
  }
});

// Call when this part of your application is removed.
unsubscribe();

Notification	Payload	Meaning
`shown`	Survey context	The widget became visibly rendered.
`dismissed`	Survey context, `completed`	The widget closed; `completed: true` means the completed survey closed.
`submitted`	`response`	The final response was accepted, including a screened-out response. Partial saves do not emit it.
`error`	`error: Error`	An SDK operation reported a failure.

There is no off() method; use the unsubscribe function. destroy() removes all listeners. Catch promises such as ready(), refresh() and show() as well: listening for notifications is not a substitute for handling a rejected call.

Survey context contains surveyId (the underlying survey ID), campaignId (the public survey ID from the dashboard or CLI), surveyVersionId, workspaceId, siteId, impressionId and language. The new fields are optional in the public types for compatibility with older notification producers; the current SDK supplies them. A dismissed notification can follow submitted when the thank-you screen closes. Use completed === false to count unfinished dismissals, rather than treating every close as abandonment.

For a supported analytics connection with selected rating exports, see PostHog integration.

SDK 0.4.0 or later can save partial responses before the visitor finishes. These saves do not emit submitted, and a later dismissed notification does not mean previously submitted answers were discarded.

Response

response is a PromptResponse:

Field	Meaning
`workspaceId`, `siteId`	Scope of the response.
`surveyId`	Underlying survey ID; it can differ from the public survey ID.
`campaignId`, `surveyVersionId`	Public survey ID and the pinned question version; optional for compatibility with older response producers.
`responseId`, `impressionId`	IDs for the accepted response and admitted display.
`answers`	Answers identified by stable `question_id`. Each answer has a discriminated `value` object.
`submittedAt`	Submission timestamp.
`language`	Optional interface language used.
`timing`	Optional aggregate survey and question interaction timing.

Answer values

`value.kind`	`value.value`
`rating`	Chosen integer.
`text`	Visitor's text.
`single_choice`	Option ID; optional `other` text alongside `value`.
`multiple_choice`	Option IDs; optional `other` text alongside `value`.
`matrix`	Object mapping row IDs to ratings.
`ranking`	Option IDs in order, most important first.
`date`	Calendar date as `YYYY-MM-DD`.
`fields`	Object mapping field IDs to strings; optional `consent: true`.

Match answers against the question version shown, not just today's edited draft. Optional unanswered questions can be absent. See Survey definition for question IDs and shapes.

Timing contains aggregate durations and counts, rather than per-keystroke content. It can include visible and active milliseconds, hidden count, validation errors, and question visits, changes, first interaction, typing duration, keystroke count and whether text was pasted.

Final responses are delivered to UserReason and included in this notification. To use a final response in your own systems as well, read it here; PromptResponse is exported from @userreason/js. Saved partial answers appear in results without this notification.