Open a survey from your own code

Your site’s own code can open and close inline, popup and chat surveys, alongside the triggers set in a survey’s Settings: after a purchase is paid, from an item in your own menu, or at a step of your web app. Embed the survey as usual, and the embed code gives your page an object to control it with.

Get the survey object

With the Script tag embed, every survey on the page is in window.voxtricsSurveys, under its ID:

window.voxtricsSurveys['YOUR_SURVEY_ID'].show();

The entry appears when the embed code runs, so call it from code that runs after the embed code, or from something the visitor does, such as a click. Embed in the survey list shows this line with the survey’s ID filled in.

With the npm package, initiateFeedbackModule returns the same object:

import { initiateFeedbackModule } from '@web-site-utilities/feedback';

const survey = initiateFeedbackModule({ formId: 'YOUR_SURVEY_ID' });
survey.show();

In React, pass a ref to FeedbackModule and call ref.current.show(). A survey placed with the <voxtrics-survey> tag, as on Wix, is in window.voxtricsSurveys too.

What the methods do

  • show() opens the survey now, without waiting for its triggers. If the survey is still loading, it opens as soon as it has loaded.
  • hide() closes the survey the way the visitor’s close button does. A popup’s button and a chat’s tab stay on the page.
  • destroy() removes the survey from the page and from window.voxtricsSurveys. Running the embed code again brings it back.

Open the survey only from your code

Add autoShow: false next to formId and the survey never opens by itself: it ignores its triggers, and a popup without a button no longer opens when the page loads. It opens when your code calls show(). A popup’s button and a chat’s tab still appear, since they are part of those survey types.

window.SiteUtilsFeedback.initiateFeedbackModule({
  formId: 'YOUR_SURVEY_ID',
  autoShow: false,
});

Leave the option out and the survey works as it always has. The <voxtrics-survey> tag doesn’t take this option.

Triggers and your code

Until your code calls show() or hide() for the first time, the survey opens by itself when its triggers are met. The first call hands the survey over to your code:

The page loads the survey.
Its triggers wait: a delay, scrolling to the end of the page, exit intent, a click on an element, a cookie.
The triggers are met first
The survey opens by itself. Its triggers stay on.
Your code calls show() or hide() first
The triggers turn off. From then on only your code and the visitor’s own controls open and close the survey.

So a survey your code opened and the visitor closed doesn’t open again when a delay or scroll trigger is met. Calling hide() before the triggers are met also keeps the survey from opening by itself.

The triggers work again after the page reloads, or after the visitor moves to a page the survey’s page rules leave out and comes back.

When show() does nothing

show() leaves the survey closed and writes the reason to the browser console when:

  • the survey’s page rules leave the current page out. Page rules always win: your code can’t show a survey on a page where it isn’t allowed;
  • the visitor has already answered the survey on this page, or on an earlier visit when Block duplicate submissions is on in the survey’s Settings;
  • the survey couldn’t load, for example because the page isn’t on the survey’s domain or the survey isn’t published;
  • it’s an on-site, email or in-app survey, which isn’t embedded on a page;
  • destroy() has been called. Only an object your code kept still answers then, since destroy() also removes the survey from window.voxtricsSurveys.

Every message the survey writes to the console starts with [Voxtrics].