Tracking survey events and processing responses

Please note: this is a developer topic.
Informizely provides a simple and effective way to react to events of the survey widget by specifying a JavaScript function when the Informizely code snippet is loaded. Such a function can be used to send data to an analytics system, to another backend system that further processes the data, or to react on certain survey widget events.

How does it work? Simply add the following code right after the line var IzWidget = IzWidget || {}; in the Informizely code snippet:
IzWidget['tracker'] = yourTrackingFunction;
yourTrackingFunction is a function that you provide and can have any name. It should be declared before the Informizely code is loaded, e.g. right before the line var IzWidget = IzWidget || {};. It should have the following signature:
yourTrackingFunction(event, surveyId, surveyName, data, api)
Parameter Type Description
event string The type of event that occurred. The possible values are descibed below.
surveyId string The ID of the current survey, or null if not applicable.
surveyName string The name of the current survey, or null if not applicable.
data object Depending on the 'event' parameter this parameter can contain extra data. This is described in the next section.
api object An API object that can be used for retrieving response data and widget manipulation. This is decribed later.

Events

The following events are passed to yourTrackingFunction if it has been specified:
"Initialized"
The Informizely code has been fully initialized.
No data. The surveyId, surveyName and data parameters are set to null.
"SurveyStart"
The survey widget is shown.
data: an object with the following properties:
PropertyTypeValue
closeAction number 0: unknown, 1: targeted.
showCount number The number of times this survey has been shown to this user.
"SurveyDone"
The survey is done. The widget may still be visible.
This event is dispatched before the data is sent to the Informizely server, so make sure that any result processing in this call is done asynchronously. Another event that can be used for processing results is "SurveyEnd".
data: an object with the following properties:
PropertyTypeValue
closeAction number 0: unknown, 1: completed, 2: closed.
completed boolean true if the survey was completed, false it is was not (it was closed prematurely by the user).
"SurveyEnd"
The survey widget is hidden.
data: an object with the following properties:
PropertyTypeValue
closeAction number 0: unknown, 1: completed, 2: closed.
completed boolean true if the survey was completed, false if it was not (it was closed prematurely by the user).
"SurveyMinimized"
The survey widget is minimized.
No data.
"SurveyMaximized"
The survey widget is maximized.
No data.
"ButtonClicked"
A call-to-action button has been clicked.
data: an object with the following properties:
PropertyTypeValue
itemId string The ID of the (button) item that was clicked.
url string The URL that was opened, or null if the button item is configured to execute JavaScript at click.
"ImageClicked"
A call-to-action image has been clicked.
data: an object with the following properties:
PropertyTypeValue
itemId string The ID of the (image) item that was clicked.
url string The URL that was opened, or null if the image item is configured to execute JavaScript at click.
"LinkClicked"
A call-to-action link has been clicked.
data: an object with the following properties:
PropertyTypeValue
itemId string The ID of the (link) item that was clicked.
url string The URL that was opened, or null if the link item is configured to execute JavaScript at click.
"PageShown"
A survey page was shown.
data: an object with the following properties:
PropertyTypeValue
pageId string The ID of the survey page that was shown.
prevPageId string The ID of the previous survey page, or null if there isn't any.
isBack boolean true if the page was shown because the user clicked the "back button", false if not.

Retrieving response data

In any call to yourTrackingFunction an api object is passed. It can be used to retrieve the answers that the user has given until now, by calling the function api.getResults(). The getResults function returns an array of result objects. A result object has the following properties:
Property Type Desciption
pageId string The ID of the survey page that contains the question for this result.
questionId string The ID of the question that was answered.
questionText string The question text.
questionType number The type of question. Values are:
  • 4: Single line of text
  • 5: Multiple lines of text
  • 6: Single choice (radio buttons)
  • 7: Multiple choices (checkboxes)
  • 8: Net Promoter Score
  • 9: Rating
answerString string A single string containing all answer data.
answers object[] An array of answer objects, one for each answer. There can be more than one answer for multi-choice questions.
Each answer object has the following properties:
  • answer (string): the answer text.
  • comment (string): for single or multi-choice questions, when there is an additional comment.
  • choiceId (string): for single or multi-choice questions: the ID of the choice that was selected

Complete example

In this example we specify a tracking function that exactly mimics the events that are sent to Google Analytics by our out-of-the-box Universal Google Analytics integration, as is described here.

<script type="text/javascript">
    function informizelyEvent(event, surveyId, surveyName, data, api)
    {
        // You can do anything that you want here. This implementation mimics Informizely's Google Analytics event tracking.
        switch (event) {
            case "SurveyMinimized":
                ga("send", "event", "Insitez", "Minimized", surveyName, { 'nonInteraction': 1 });
                break;
            case "SurveyMaximized":
                ga("send", "event", "Insitez", "Maximized", surveyName, { 'nonInteraction': 1 });
                break;
            case "SurveyStart":
                ga("send", "event", "Insitez", "Shown", surveyName, { 'nonInteraction': 1 });
                break;
            case "ButtonClicked":
                ga("send", "event", "Insitez - " + surveyName, (data.url == null) ? "Button Click - JavaScript" : "Button Click - URL",
                   data.itemId, { 'nonInteraction': 1 });
                break;
            case "ImageClicked":
                ga("send", "event", "Insitez - " + surveyName, (data.url == null) ? "Image Click - JavaScript" : "Image Click - URL",
                   data.itemId, { 'nonInteraction': 1 });
                break;
            case "LinkClicked":
                ga("send", "event", "Insitez - " + surveyName, (data.url == null) ? "Link Click - JavaScript" : "Link Click - URL",
                   data.itemId, { 'nonInteraction': 1 });
                break;
            case "SurveyDone":
                ga("send", "event", "Insitez", data.completed ? "Completed" : "Canceled", surveyName, { 'nonInteraction': 1 });
                var results = api.getResults();
                for (var index = 0; index < results.length; index++) {
                    var result = results[index];
                    ga("send", "event", "Insitez - " + surveyName, result.questionText, result.answerString, { 'nonInteraction': 1 });
                }
                break;
            case "Initialized":
            case "PageShown":
            case "SurveyEnd":
            default:
                // Not used for GA tracking.
                break;
        }
    }

    var IzWidget = IzWidget || {};
    IzWidget['tracker'] = informizelyEvent;

    // Add the normal Informizely code snippet below.
    (function (d) {
        ...	
    }) (document);
</script>