Overview
The Survicate JavaScript API allows you to trigger and adjust the behaviour of websites and web-app surveys.
JavaScript methods used to trigger Survicate surveys, except setVisitorTraits
can only be used on some of the paid plans. Check our pricing page for more details. We refer to this feature as 'Advanced Targeting' or 'JavaScript Targeting'.
Using NPM packages
This section applies only to users, who decided to install Survicate tracking code either via the npm web surveys package, or npm wrapper.
Before calling any of the methods or appending event listeners, you need to initialize the Survicate JavaScript API.
Please note: In Web Surveys wrapper initSurvicate is asynchronous, so the user has to await its resolution. This should be done once, when initSurvicate hass been resolved, user can refer to getSurvicateInstance()
as in provided example. Handling asynchronous code depends on the use case.
Methods
Set visitor attributes
To set the visitor attributes asynchronously after the script is loaded, you can use the setVisitorTraits
method.
Please note: The visitor attributes will be updated locally straight away, but the change will be visible in Survicate as soon as they answer any question.
Retarget
Survicate triggers the targeting script to determine if a survey should be displayed to a user. This happens during events like a page load, the completion of a survey, or a path change in the 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
As soon as your user answers any survey's question, we assign a unique ID to them. Feel free to identify your users using that ID with the getVisitorId method
Please note: The output of this method can be null
. As mentioned above, the value is assigned only to the visitors that have answered any question.
Reset visitor
Using the destroyVisitor
method you can remove a user's browser data. This erases data like session history and survey responses from their localStorage and sessionStorage. However, responses already saved in our database remain untouched and can still be viewed in the survey results tab.
Be cautious:
-
If a user matches a survey's targeting criteria, they might encounter the same survey again.
-
If you use this method while a survey is in progress, the survey will close and the user won't be able to complete it.
When using the destroyVisitor
method, you can include a callback function to execute a specific action afterward. In this example, the callback function triggers the retarget method, which will ‘check’ if there are surveys that should be shown to this 'new' user.
Show survey
For the customers that need a custom 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 ignores all targeting options, except checking whether this visitor has already answered the survey.
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).
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. Survey will be shown regardless of whether the user has already answered this 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'. |
Disabling automatic targeting
The targeting script is automatically executed to determine if a user fits the specified criteria. We recognize that some users might prefer a different approach, such as using custom targeting with the showSurvey
method. If you'd like to turn off this automatic feature, use the disableTargeting
property.
Event-based targeting
If you need to display a survey after your site's visitor performs a specific action, use our event-based targeting. You can consider any action from your users' behavior as an event. For example, you might be interested in triggering a survey for those users who've just left the cart page without finishing the purchase. Or for those users who've just downgraded their subscription, etc.
In order to show surveys based on triggered events you can use invokeEvent
method.
If only event name was provided in panel, pass it's name as an argument to invokeEvent
method.
If also event properties were provided in panel, pass them as an object to invokeEvent
method as second argument.
Important to note: Event name, properties keys and values are case sensitive. If there is any discrepancy between what's declared in the ‘Triggers’ tab of the Target section in the Survicate panel and the code, the survey will not appear.
Submit survey answers without displaying a survey
In advanced scenarios, you may want to programmatically submit answers to Survicate surveys without showing the survey widget to the user. This is possible using the hiddenSurveys
, getSurveyPointsMetadata
and submitAnswer
method.
This feature works for Text, Single, Rating, Numerical, CSAT and NPS.
1. Setting your survey frequency
In order to accept multiple responses in a short time, you need to set your survey frequency to: "If the user has responded or closed the survey - Let the user take the survey multiple times on a recurring basis - Every time a respondent matches required criteria"
2. Hiding surveys from the UI
To prevent specific surveys from being displayed, pass their IDs to the Survicate tracking code using the hiddenSurveys
property. This ensures the surveys are hidden from the user interface, but remain accessible via the API.
You can verify which surveys are hidden by checking:
Note: Hidden surveys will not appear on the page, but you can still interact with them programmatically.
3. Retrieving survey points metadata
Before submitting an answer, you need to know the available questions (points) and possible answers for a given survey. Use the getSurveyPointsMetadata
method:
This returns an array of objects, each describing a survey point (question) and its possible answers:
pointId
: The unique ID of the question.answerType
: The type of answer expected (e.g., text, rating, single choice).answers
: Optional, an array of possible answer IDs (for choice-based questions).
4. Submitting an answer
Once you have the point and answer IDs, use the submitAnswer
method to send a response:
Example: Submitting a Rating answer
Example: Submitting a Text answer
Tip: For NPS questions, provide the score as the
answer
(a number between 0 and 10).
5. Error Handling
The API provides informative console warnings if something goes wrong, such as:
Survey with ID "7d9d103a77b389ss25" not found
Point with ID "1319371113" not found in survey "7d9d103a77b38925"
Answer ID "2418281111" not found in point "1319375" of survey "7d9d103a77b38925"
Check the browser console for these messages during development and debugging.
6. Verifying Submissions
All answers submitted via the API will be visible in the Survicate Analyze tab for your workspace.
7. Best Practices
- Always retrieve the latest survey points metadata before submitting answers
- Validate your input (IDs, answer types) to avoid unnecessary errors.
- Use
hiddenSurveys
only for surveys you intend to control programmatically.