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(surveyId, pageIndex?)

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.

Parameter	Type	Required	Default
surveyId	string	Yes	—
pageIndex	number	No	0

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(id?)

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

Parameter	Type	Required
id	string	No

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(pageIndex)

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

Parameter	Type	Required
pageIndex	number	Yes

window.USETIFUL.surveys.goToPage(pageIndex)

Example

window.USETIFUL.surveys.goToPage(2);

---

showLaterSurvey(id?, duration?, timeUnit?)

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

Parameter	Type	Required
id	string	No
duration	number	No
timeUnit	string	No

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

Example

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

---

isSurveyCompleted(surveyId)

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

Returns: boolean

Parameter	Type	Required
surveyId	string	Yes

window.USETIFUL.surveys.isSurveyCompleted(surveyId)

Example

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

---

completeSurvey(surveyId)

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.

Parameter	Type	Required
surveyId	string	Yes

window.USETIFUL.surveys.completeSurvey(surveyId)

Example

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

---

uncompleteSurvey(surveyId)

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.

Parameter	Type	Required
surveyId	string	Yes

window.USETIFUL.surveys.uncompleteSurvey(surveyId)

Example

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