NAV Navbar
JavaScript

JavaScript API

Introduction

Survicate library loaded on your page provides the _sva object that can be used to execute a number of helpful methods allowing the visitors and surveys management.

Configuration

The _sva object allows you to pre-configure the behavior of the Survicate script, by attaching an additional configuration code before the regular tracking code.

Traits

(function(opts) {
  opts.traits = {
    "email": "Respondent's email",
    "first_name": "Respondent's name",
    "last_name": "Respondent's last name", 
    "my_custom_attribute": "Custom attribute value"
  };
})(window._sva = window._sva || {});

You can pass custom visitor attributes from your website or application. We’ve reserved some attributes that we handle in a special way. For example, we always expect email to be a string of the user’s email address.

Reserved attributes we’ve standardized:

Disable automatic targeting

(function(opts) {
  opts.disableTargeting = true;
})(window._sva = window._sva || {});

The visitors targeting script is run automatically every time there is a need to verify if a visitor matches the targeting configuration. We understand that for some users this isn't the desired behavior, e.g. custom targeting using the _sva.showSurvey method. If you wish to disable this feature, you can use the disableTargeting property.

Methods

Retarget

_sva.retarget();

Survicate fires the visitors targeting script whenever there is a need to find out, whether there is a survey that should be displayed to your visitor, for instance on such events as page load, survey's completion or path change in your Single Page Application. If you'd like to trigger an additional targeting script execution, you can use the retarget method.

This feature can be especially useful for Single Page Applications / Progressive Web Applications or the callbacks of asynchronous methods.

Get visitor ID

var visitorId = _sva.getVisitorId();

As soon as your visitor answers any survey's question, we assign a unique ID to them. Feel free to keep your visitors using that ID using the getVisitorId method.

Set visitor traits

_sva.setVisitorTraits({
  "email": "Respondent's email",
  "first_name": "Respondent's name",
  "last_name": "Respondent's last name", 
  "my_custom_attribute": "Custom attribute value"
});

To set the visitor attributes asynchronously after the script is loaded, you can use the setVisitorTraits method.

Reset visitor

_sva.destroyVisitor(function() {
  console.log('Visitor destroyed.');
});

To reset the visitor and let one be treated as a new respondent or answer one survey multiple times, you can use the destroyVisitor method. This method resets all visitor's data, including their attributes, sessions and answered surveys that are stored in their localStorage / sessionStorage. This method will not change any data that Survicate has already collected. If you wish to remove that data, please visit our app.

You can optionally provide callback function as a first parameter that will be triggered after visitor cleanup.

_sva.destroyVisitor(_sva.retarget);

Show survey

_sva.showSurvey('abc1234');

For the customers that need even more advanced targeting system, we provide the showSurvey method, that makes it easy to show an arbitrary survey based on the given survey's id. The method returns true if the survey was rendered and false otherwise (e.g. another survey is already displayed or the visitor has answered the desired survey).

var options = {
  forceDisplay: true,
  displayMethod: 'delayed',
  displayOptions: {
    delay: 5
  }
};

_sva.showSurvey('abc1234', options);

Optionally, to change the default behavior of the survey, you can provide the options object as the second parameter.

options

Property Type Description
forceDisplay boolean If true, currently rendered survey will be closed in favor of the new survey.
displayMethod string Use this option in order to overwrite the current displaying configuration. Possible values: ['immediately', 'delayed', 'exitIntent', 'onScroll'].
displayOptions object See below for available options. Applicable and required only for the displayMethod values 'delayed' and 'onScroll'.

displayOptions

Property Type Description
delay integer Delay in seconds. Applicable and required only for displayMethod = 'delayed'.
scrolledPercentage integer Percentage of the page that was already scrolled. Applicable and required only for displayMethod = 'onScroll'.

Events

var listenerId = _sva.addEventListener('event', callback);

Survicate provides a number of events that you might find useful to trigger certain actions in your application based on the visitor's actions. You can set up listeners to hook into these events. By calling the _sva.addEventListener method multiple times, you can set up more than one listener for a given event.

// Remove an event listener based on its id
_sva.removeEventListener(listenerId); 

// Remove all listeners hooked into a given event
_sva.removeEventListener('question_answered');

If you don't need the listener anymore, you can use _sva.removeEventListener method to remove the previously registered listener. It is possible to remove either all the listeners that are hooked into a given event or a single listener based on the listenerId returned from the _sva.addEventListener method.

Survey displayed

_sva.addEventListener('survey_displayed', function(surveyId) {
  // do stuff
});

Every display of a survey is followed by the survey_displayed event emission.

Question answered

_sva.addEventListener('question_answered', function(surveyId, questionId, answer) {
  // do stuff
});

As soon as the visitor answers a question, Survicate emits the question_answered event.

Answer object properties

Property Type Description
answer_type string Answer type.
answer_id integer Answer ID. Applicable only for type = ['single', 'smiley_scale', 'dropdown_list'].
answer_ids integer[] Array of answer IDs. Applicable only for type = ['multiple'].
answer_value string Context value of the answer. Applicable only for type = ['text', 'nps', 'date', 'rating'].

Survey completed

_sva.addEventListener('survey_completed', function(surveyId) {
  // do stuff
});

Once a survey has been completed, Survicate emits the survey_completed event. Survey is considered to be completed, when a visitor has answered every single question that was displayed to them in the configured flow.

Survey closed

_sva.addEventListener('survey_closed', function(surveyId) {
  // do stuff
});

If at any stage of the survey, your visitor clicks the close button, Survicate will emit the survey_closed event.

Script loaded

window.addEventListener('SurvicateReady', function() {
  // do stuff
});

As soon as the Survicate script has been fully loaded and ready, you will be informed through the SurvicateReadywindow event. This event is especially useful for the Single Page Applications / Progressive Web Applications.

Support

👋 If you bump into any problems or need more support, just start a conversation using Intercom in the bottom-right corner and you will be immediately routed to our Customer Support Engineers.