Show a survey

Use show() for a deliberate request to display one survey, such as a feedback button. For a business action that should be recorded, use event().

Signature

UserReason.show(surveyId: string, options?: ShowOptions): Promise<boolean>

Example

This example adds a feedback button. Replace both placeholders with IDs from the same site. Configure the published survey with a page-load trigger. Disabling automatic triggers keeps it from opening before the button is clicked.

import UserReason from '@userreason/js';

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

const button = document.createElement('button');
button.type = 'button';
button.textContent = 'Give feedback';
button.addEventListener('click', async () => {
  try {
    const displayed = await UserReason.show('YOUR_PROMPT_ID');
    if (!displayed) console.info('No feedback survey is available right now.');
  } catch (error) {
    console.error('Could not display feedback', error);
  }
});
document.body.append(button);

Run in the browser after the document body exists. Initialize once for your app; do not add a second initialization with different options to an existing integration.

Rules still apply

Managed show() evaluates a page-load opportunity for the selected survey. The survey must have a matching page-load trigger. An event-only survey remains ineligible; show() cannot fabricate an application event.

The survey must be published, supported by the installed SDK, in the visitor's sampled cohort and eligible for its audience and server frequency rules. A permanent decline also prevents display. Only one UserReason widget can be open at a time.

force: true only skips the SDK's own shortcut for surveys the API said are held. It does not bypass sampling, audience, server frequency, permanent decline or trigger matching. Use a development site and a fresh visitor when testing.

Return value and errors

true means the widget was mounted; it does not mean the visitor saw every question or submitted a response. Use the shown and submitted notifications for those lifecycle moments.

false means it could not display, including failed eligibility, a missing document body, another active widget, or execution outside a browser. Calling before initialization in the browser throws; an unknown published survey ID rejects. Loading and network failures can also reject, so catch the promise.