Engagement / On-Site / Survey

Survey Settings

Survey Configuration Properties

Property
Type
Description
Default

surveyId

String

To show a specific survey, specify the surveyId

null

skipRules

boolean

If set to true, targeting rules specified in the dashboard for the active surveys are not executed. Thus, all the active surveys, unless surveyId is specified, become eligible to be shown.

false

forcedRender

boolean

If set to true, the submitted or closed surveys also become elgible to be shown.

false

defaultRender

boolean

If set to false, the eligible survey is not displayed by default.

true

delay

number

Time delay, in miliseconds, to show a survey on a page. It overrides the time delay specified in the dashboard.

As set in the dashboard

scope

string/object

A visitor life cycle depends on a long term cookie installed for your site in a browser. Lifecyle of a survey depends on the scope of a visitor. If a survey is closed, it doesn't appear for the visitor in the same browser session. If a survey is submitted, then it doesn't appear for the same visitor at all. If you want a survey to appear in every new browser session irrespective of the survey being taken in a past session, you can define your own scope. In this case, specify scope as SESSION_ID and the lifecycle of a survey remains within the scope of a session id. See examples below -

null

scopeType

String

By defining custom scope, you can make a survey submitted once in that scope. By specifying the scopeType as 'session', you can narrow a scope within that session, making a possibility of a survey appearing multiple times to a visitor per each scope. By specifying the scopeType as 'global', you can make a survey submitted once per each scope value across different browser sessions/visitors.

session

customData

object

Specify your custom data for survey in proper JSON format to submit along with every survey submission. If not set then webengage.customData is referred

null

ruleData

object

Specify your rule data here in proper JSON format to filter you audience, with the keys you specified in the WebEngage Dashboard while editing rule for the corresponding Survey. If not specified webengage.ruleData is referred

null

Examples of using Survey Properties

Pass business data for custom rules
webengage.survey.options('ruleData', {
	'itemsInCart' : 3,
	'cartAmount' : 1288,
	'customerType' : 'gold'
});
Show surveys to a visitor everytime a new browser session starts

By specifying a session_id (some unique identifier for a browser session) as the survey scope with scopeType as 'session', one can make a survey re-appear to a visitor, even if (s)he has closed or submitted it in a previous browser session.

webengage.survey.options({
	'scope' : '_USER_SESSION_ID_',
	'scopeType' : 'session'
});

Note : Notice that options method either takes key-value pair as input or a Javascript map.

Show a survey to a visitor every day irrespective (s)he has closed/submitted the same survey.

By specifying a today's date as the survey scope, one can make a survey re-appear to a visitor each day even if he has closed or submitted it.

var today = new Date();
webengage.survey.options('scope', {
	'scope' : (today.getDate()+"-"+today.getMonth()+"-"+today.getYear()),
	'scopeType' : 'session',
	'surveyIds' : ["~29aj48l"]
});
Show a survey once to a logged in user from different browsers

If one wants a survey to be submitted once per logged in user irrespective of different browser sessions, then specify logged in user's email or userId as the scope with scopeType as 'global'.

webengage.survey.options({
	'scope' : '_USER_EMAIL_',
	'scopeType' : 'global'
});

Survey Callbacks

Callback Description Callback Data
onOpen invoked on survey open Object
onClose invoked when a survey is closed Object
onSubmit invoked when a question is answered Object
onComplete invoked when the thank you message is displayed in the end Object

Examples of using Survey Callbacks

Close survey after certain response of a particular question
webengage.init('_LICENSE_CODE_');
webengage.survey.onSubmit(function (data) {
    var surveyInstance = this;
    if(data !== undefined && data.questionResponses !== undefined && data.questionResponses.length > 0) {
        for(var i=0; i < data.questionResponses.length; i++) {
            var question = data.questionResponses[i];
            if(question["questionId"] === "324saf3w") {
                var questionResponse = question["value"];
                var values = questionResponse["values"];
                if(values !== 'undefined' &&  values.length > 0){
                    for(var k=0; k < values.length; k++) {
                        if(values[k] === 'RED') {
                            surveyInstance.close();
                            break;
                        }
                    }
                }
                break;
            }
        }
    }
});
Redirect a user on survey completion
webengage.survey.onComplete(function () {
    window.location.href='/newletter/subscribe.html';
});

Survey onOpen callback data (JSON)

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://webengage.net/",
		"pageTitle": "In-site customer Feedback, targeted Surveys & push Notifications for Websites - WebEngage",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "India",
		"region": "Maharashtra",
		"city": "Mumbai",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "john" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	}
}

Survey onSubmit callback data (JSON)

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://webengage.net/",
		"pageTitle": "In-site customer Feedback, targeted Surveys & push Notifications for Websites - WebEngage",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "India",
		"region": "Maharashtra",
		"city": "Mumbai",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "john" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	},
	"questionResponses": [{
		"questionId": "~1fstl7a",
		"questionText": "What is your favourite color?",
		"value": {
				"@class": "list",
				"values": ["Red"]
		}
	}]
}

Survey onComplete callback data (JSON)

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://webengage.net/",
		"pageTitle": "In-site customer Feedback, targeted Surveys & push Notifications for Websites - WebEngage",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "India",
		"region": "Maharashtra",
		"city": "Mumbai",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "john" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	},
	"questionResponses": [
	{
		"questionId": "~1fstl7a",
		"questionText": "Your name?",
		"value": {
			"@class": "map",
			"values": {
				"First name": "ABC",
				"Last name": "EFG"
			}
		}
	},
	{
		"questionId": "~1asf233",
		"questionText": "Enter your mobile number?",
		"value": {
			"@class": "text",
			"text": "9988776655"
		}
	},
	{
		"questionId": "we2e4545",
		"questionText": "Your Bio?",
		"value": {
			"@class": "text",
			"text" : "I am an early beta user of this product."
		}
	},
	{
		"questionId": "324saf3w",
		"questionText": "What is your favourite color?",
		"value": {
			"@class": "list",
			"values": ["Red"]
		}
	},
	{
		"questionId": "~213wrw43s",
		"questionText": "Which countries you have been to?",
		"value": {
			"@class": "list",
			"values": [ "US", "Mexico" ]
		}
	},
	{
		"questionId": "~ew347fev"
		"questionText": "Rate out website?",
		"value": {
			"@class" : "matrix",
			"values" : {
				"Experience" : [ "Good" ],
				"Content" : [ "Good" ],
				"Design" : [ "Poor" ]
			}
		}
	},
	{
		"questionId": "sht4k8",
		"questionText": "Upload your resume?",
		"value": {
			"@class" : "file",
			"fileName" : "android_sdk_developing.pdf",
			"fileSize" : 1919972,
			"fileAccessUrl" : "https://api.webengage.com/v1/download/feedback/response/ofq4jy",
			"fileType" : "pdf"
		}
	}]
}

Survey onClose callback data (JSON)

On survey close, the callback data for close event will be the same as the last event (whether Open, Submit or Complete) for that survey.

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://webengage.net/",
		"pageTitle": "In-site customer Feedback, targeted Surveys & push Notifications for Websites - WebEngage",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "India",
		"region": "Maharashtra",
		"city": "Mumbai",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "john" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	}
}

Survey Methods

webengage.survey.render

This method allows you to override survey settings as configured in the dashboard. It also overrides any provided global widget settings on the page. This method accepts all survey configuration properties.

Name Type Description
options Object Survey configuration properties & Callbacks

Examples of Render Method

Open a survey on click of a button
webengage.survey.options({
	'surveyId' : '_SURVEY_ID_', // survey id to be rendered ... note : it is optional
	'defaultRender' : false
});
webengage.onReady(function(){
	document.getElementById("_BUTTON_ID_").onclick = function () {
		webengage.survey.render();
	};
});
Open a survey on page scroll (down)
webengage.survey.options({
	'defaultRender' : false
});
(function () {
	var getScrollPercentage = function () {
		var documentHeight = $(document).height();
		var viewPortHeight = $(window).height();
		var verticlePageOffset = $(document).scrollTop();
		return Math.round(100* (viewPortHeight+verticlePageOffset)/documentHeight);
	}
	var surveyDisplayed = false;
	webengage.onReady(function(){
		window.onscroll = function (event) {
			if (!surveyDisplayed && getScrollPercentage() >= 70) {
				webengage.survey.render({ surveyId : '_SURVEY_ID_' }); // invoking webengage.survey.render with specific survey id
				surveyDisplayed = true;
			}
	}
	});
})();

Please scroll down, till the end to see this in effect.
Also, notice that we are calling webengage.survey.render by passing it surveyId option.

Passing Custom Data / Rule Data
webengage.survey.options({
	'defaultRender' : false
});
webengage.survey.options('ruleData', { 'categoryCode' '_CATEGORY_CODE_', 'paidCustomer' : true });
webengage.onReady(function(){
	document.getElementById("_BUTTON_ID_").onclick = function () {
		webengage.survey.render({
			'customData' :  { 'userId' : '_USER_ID_', 'age' : _AGE_ }
		});
	};
});
Track survey view in console
webengage.survey.options({
	'defaultRender' : false
});
webengage.onReady(function(){
	document.getElementById("_BUTTON_ID_").onclick = function(){
		webengage.survey.render().onOpen( function(){
			console.log("survey open");
		});
	};
});

webengage.survey.clear

Clears any rendered survey.

Examples of Clear Method

Clear a survey on click of a button
webengage.onReady(function(){
	document.getElementById("_BUTTON_ID_").onclick = function () {
		webengage.survey.clear();
	};
});

Engagement / On-Site / Survey