Skip to main content

Surveys​

The survey methods allow you to display surveys, navigate between pages, snooze surveys, and manage completion state. All methods are available on window.USETIFUL.surveys after the usetiful:fullApiReady event has fired.

Survey IDs are string identifiers assigned in the Guides and Surveys dashboard when creating or editing a survey. Multi-page surveys use 0-indexed page numbers.

start​

Displays a survey by its ID. By default, the survey opens on the first page (index 0). Use the pageIndex parameter to open the survey on a specific page.

Parameters
  • surveyId string required

    The survey ID.

  • pageIndex number optional

    Default value: 0

    The page to open (0-indexed).

window.USETIFUL.surveys.start(surveyId, pageIndex?)

Example​

// Open a survey on its first page
window.USETIFUL.surveys.start('survey-1');

// Open a survey on page 3 (0-indexed)
window.USETIFUL.surveys.start('survey-1', 2);

close​

Closes a survey. When an id is provided, that specific survey is closed. When called without arguments, the currently active survey is closed.

Parameters
  • id string optional

    The survey ID to close. When omitted, closes the active survey.

window.USETIFUL.surveys.close(id?)

Example​

// Close the active survey
window.USETIFUL.surveys.close();

// Close a specific survey by ID
window.USETIFUL.surveys.close('survey-1');

goToNextPage​

Advances to the next page of the currently active survey. If the survey is on its last page, calling this method has no effect.

window.USETIFUL.surveys.goToNextPage()

Example​

window.USETIFUL.surveys.goToNextPage();

goToPage​

Jumps to a specific page of the currently active survey. Pages are 0-indexed.

Parameters
  • pageIndex number required

    The page to jump to (0-indexed).

window.USETIFUL.surveys.goToPage(pageIndex)

Example​

window.USETIFUL.surveys.goToPage(2);

showLaterSurvey​

Snoozes a survey so that it reappears after a specified delay. When called without arguments, the currently active survey is snoozed with the default delay configured in the dashboard.

Provide duration and timeUnit to set a custom snooze period. Supported time units include 'minutes', 'hours', and 'days'.

Parameters
  • id string optional

    The survey ID to snooze. When omitted, snoozes the active survey.

  • duration number optional

    The snooze duration.

  • timeUnit string optional

    The time unit for duration. One of 'minutes', 'hours', or 'days'.

window.USETIFUL.surveys.showLaterSurvey(id?, duration?, timeUnit?)

Example​

// Snooze a survey for 3 days
window.USETIFUL.surveys.showLaterSurvey('survey-1', 3, 'days');

isSurveyCompleted​

Returns whether a survey has been completed by the current user.

Returns: boolean

Parameters
  • surveyId string required

    The survey ID.

window.USETIFUL.surveys.isSurveyCompleted(surveyId)

Example​

const done = window.USETIFUL.surveys.isSurveyCompleted('survey-1');

completeSurvey​

Manually marks a survey as completed for the current user. Use this method when you need to mark a survey as done without the user having submitted it through the UI, for example after processing the response in your own application logic.

Parameters
  • surveyId string required

    The survey ID.

window.USETIFUL.surveys.completeSurvey(surveyId)

Example​

window.USETIFUL.surveys.completeSurvey('survey-1');

uncompleteSurvey​

Removes the completed status from a survey for the current user, allowing it to be displayed again. Use this method when a survey needs to be re-shown, for example after a product update that warrants collecting new feedback.

Parameters
  • surveyId string required

    The survey ID.

window.USETIFUL.surveys.uncompleteSurvey(surveyId)

Example​

window.USETIFUL.surveys.uncompleteSurvey('survey-1');