Legacy SDK v4

JavaScript API (Version 4.0)

Once you sign-up and integrate Webengage Widget Code on your web-site, you can use this Javascript API to change the default behaviour of how the Surveys, Feedback and Notifications work on your site to suit your needs.

Integration Code and API

Default Integration Code

Following is the default one time integration code snippet -

<script id="_webengage_script_tag" type="text/javascript">
    var _weq = _weq || {
        'webengage.licenseCode' : '_LICENSE_CODE_'
    };
    (function(d){
    var _we = d.createElement('script');
    _we.type = 'text/javascript';
    _we.async = true;
    _we.src = (d.location.protocol == 'https:' ? _WIDGET_SSL_DOMAIN_ : _WIDGET_DOMAIN_ ) + "/js/widget/webengage-min-v-4.0.js";
    var _sNode = d.getElementById('_webengage_script_tag');
    _sNode.parentNode.insertBefore(_we, _sNode);
  })(document);
</script>

This code loads and initializes WebEngage Widget asynchronously, so it does not block loading of your web page. This is cautiously done to not impact page load time on your website. The URLs in the above code are protocol relative. This lets the browser to load the widget over the same protocol (HTTP or HTTPS) as the containing page, which will prevent "Insecure Content" warnings.

Initialization

All widget configuration parameters are set in a global JavaScript object called _weq. Once the WebEngage Widget JavaScript loads, it initialises the widget based on _weq map properties. The default shipped integration code sets the licenseCode key in the _weq map. Similarly, you can set other widget properties and callback functions in the _weq map.

Global Configuration (_weq Map)

All global and static configuration either at the widget level or individual product (Feedback, Survey or Notification) level are set in a global map named _weq . This configuration includes set of properties as well as callback event handlers (functions). The complete set of keys supported in the _weq are listed in the tables below:

Widget Settings

Widget Configuration Properties

PropertyTypeDescriptionDefault
licenseCode*StringRegistered license code for the website. You can get it from your Webengage dashboard if registered, otherwise signup to get your licenseCode.N/A
language*StringSpecify your widget language here. The static messages present in your feedback/survey form will appear in the language specified here.As per settings in the dashboard
delay*numberDelays API initialization for the time specified (in milliseconds).0
defaultRenderbooleanIf set to false, then by default on widget initialization, none of the products (feedback, survey and notification) appears. To stop rendering selective products from rendering, set the defaultRender at the product level configuration properties.true
customDataobjectSpecify your custom data here in proper JSON format to submit along with every survey / feedback submission and notification clicknull
ruleDataobjectSpecify your rule data here in proper JSON format. The keys should match with the values used in Targeting rules section for the corresponding Survey or Notificationnull
tokensobjectSpecify your tokens data here in proper JSON formatnull
enableCallbacksbooleanIf set to true, will enable callbacks for all the events of feedback, survey and notificatontrue

* Property used only at the init time, changing this property later will have no effect

Examples of using Widget Configuration Properties

1. Load WebEngage widget after 5 seconds

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.delay'] = 5;

2. Pass your own custom/business data for tracking (e.g. userId, email, sessionId etc.)

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.customData'] = { 'userId' : '2947APW09', 'age' : 21, 'isPaidCust' : false };

This data will be passed to all the activated products Survey,Feedback and Notification unless their own specific custom data (eg. webengage.feedback.customData ) is provided.

3. Hide WebEngage by default on mobile and tablets

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';

var isMobile = {
    Android: function() {
            return navigator.userAgent.match(/Android/i);
    },
    BlackBerry: function() {
            return navigator.userAgent.match(/BlackBerry/i);
    },
    iOS: function() {
            return navigator.userAgent.match(/iPhone|iPad|iPod/i);
    },
    Opera: function() {
            return navigator.userAgent.match(/Opera Mini/i);
    },
    Windows: function() {
            return navigator.userAgent.match(/IEMobile/i);
    },
    any: function() {
            return (isMobile.Android() || isMobile.BlackBerry() || isMobile.iOS() || isMobile.Opera() || isMobile.Windows());
    }
};

if (isMobile.any()) {
    _weq['webengage.defaultRender'] = false;        
}

Widget Callbacks

CallbackTypeDescriptionDefault
onReadyFunctionAny code that you want to run after the API is loaded and initialized should be placed within the webengage.onReadynull

Examples of using Widget Callback

1. Show a survey on click of a button instead of default rendering

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
//default rendering is disabled
_weq['webengage.survey.defaultRender'] = false;
_weq['webengage.onReady'] = function(){
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.survey.render();
    };
};

Global Methods

webengage.track

This method allows you to pass business events to WebEngage for analytics or to trigger surveys/notifications.

All passed events are captured in the event analytics screen (coming soon)

Parameters

NameTypeDescription
eventNameStringName of the event that occurred
eventDataObjectData to associate with the event. Pass a simple object with only strings, numbers, booleans and dates as property values

Example of a webengage.track call

1. Let WebEngage know when a visitor leaves a cart before checkout
webengage.track('cartAbandoned', { userID: 1337, country: 'India' });

Survey Settings

Survey Configuration Properties

PropertyTypeDescriptionDefault
surveyIdStringTo show a specific survey, specify the surveyIdnull
skipRulesBooleanIf 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
forcedRenderBooleanIf set to true, the submitted or closed surveys also become elgible to be shown.false
defaultRenderBooleanIf set to false, the eligible survey is not displayed by default.true
delayNumberTime delay, in miliseconds, to show a survey on a page. It overrides the time delay specified in the dashboard.As set in the dashboard
scopeString/ObjectA 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
scopeTypeStringBy 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
customDataObjectSpecify your custom data for survey in proper JSON format to submit along with every survey submission. If not set then webengage.customData is referrednull
ruleDataObjectSpecify 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 referednull
enableCallbacksBooleanIf set to true, will enable callbacks for all the survey events.false

Examples of using Survey Properties

1. Pass business data for custom rules

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.ruleData'] = {
    'itemsInCart' : 3,
    'cartAmount' : 1288,
    'customerType' : 'gold'
};

2. 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.

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.scope'] = "_USER_SESSION_ID_";
_weq['webengage.survey.scopeType'] = "session";

3. 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 _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
var today = new Date();
_weq['webengage.survey.scope'] = {
    'scope' : (today.getDate()+"-"+today.getMonth()+"-"+today.getYear()),
    'scopeType' : 'session',
    'surveyIds' : ["~29aj48l"]
};

4. Show a survey once to a logged in user from differernt 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'.

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.scope'] = '_USER_EMAIL_';
_weq['webengage.survey.scopeType'] = 'global';

Survey Callbacks

CallbackDescriptionCallback data
onOpeninvoked on survey openObject
onCloseinvoked when a survey is closedObject
onSubmitinvoked when a question is answeredObject
onCompleteinvoked when the thank you message is displayed in the endObject

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 handlers will the latest event's (Open, Submit or Complete) callback data that happened before close.

Lets say if you close a survey after it opens the callback data for close event would same as the onOpen callback data as mentioned above.

{
        "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" ]
        }
}

Examples of using Survey Callbacks

1. Close survey after certain response of a particular question

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.enableCallbacks'] = true;
_weq['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;
            }
        }
    }
};

2. Redirect a user on survey completion

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.onComplete'] = function () {
    window.location.href='/newletter/subscribe.html';
};

Survey Methods

1. webengage.survey.render

This method allows you to overwrite the dashboard settings. It also overwrites the settings provided in _weq in the widget code. This method accepts all the _weq survey configuration properties and _weq callbacks.

NameTypeDescription
optionsObjectSurvey configuration properties callbacks

Examples of Render Method

1. Open a survey on click of a button

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.surveyId'] = '_SURVEY_ID_'; // survey id to be rendered ... note : it is optional
_weq['webengage.survey.defaultRender'] = false;
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.survey.render();
    };
};

2. Open a survey on page scroll (down)

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = 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;
    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.

3. Passing Custom Data / Rule Data

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.survey.ruleData'] = { 'categoryCode' '_CATEGORY_CODE_', 'paidCustomer' : true };
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.survey.render({
            'customData' :  { 'userId' : '_USER_ID_', 'age' : _AGE_ }
        });
    };
};

4. Tracking survey view in console

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function(){
    document.getElementById("_BUTTON_ID_").onclick = function(){
        webengage.survey.render().onView( function(){
            console.log("survey open");
        });
    };
};

2. webengage.survey.clear

Clears rendered survey.

Examples of Clear Method

1. Clear a survey on click of a button

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.survey.clear();
    };
};

Feedback Settings

Feedback Configuration Properties

PropertyTypeDescriptionDefault
delayNumberTime delay, in milliseconds, to show the feedback tab on a page.null
formDataArray of ObjectSpecify values in the feedback form for the pre-population of the fields. examplenull
alignmentstringShows the feedback tab on the left/right side of the webpage. The possible value that you can specify here is left or right.As specified in feedback tab configuration
borderColorstringRenders feedback tab with the specified border colorAs specified in feedback tab configuration
backgroundColorstringRenders feedback tab with the specified background colorAs specified in feedback tab configuration
defaultCategorystringShows the feedback form based on the feedback category specified here.As specified in feedback tab configuration
showAllCategoriesbooleanIf set to true, the feedback form appears with feedback category drop down menu to let the end users to submit contextual feedbacks. If set to false, the feedback form appears based on the default feedback category specified without any feedback category dropdown menu.true
showFormbooleanIf set to true, feedback form slides out, on page load, by default.false
defaultRenderbooleanIf set to false, the feedback tab is not displayed by default.true
customDataobjectSpecify your custom data here in proper JSON format to submit along with every feedback got submitted, if not specified webengage.data is referred.null
enableCallbacksbooleanIf set to true, will enable callbacks for all the feedback events.false

formData Object

PropertyTypeDescription
nameStringLabel of the field in the feedback form which you want to prepopulate data or want to hide or make it mandatory
valueStringSpecify the value of the field
modeStringSpecify if the field should be hidden, read only or default (no-change). So values only supported are hidden and readOnly and default
isMandatoryBooleanSpecify if the field should be mandatory or not
optionsString ArrayApplicable only in case of ‘Category’ field. Specify in case you want to show specific values in the category dropdown

NOTE : To see the example code click here

Examples of using Feedback Properties

1. Set feedbackTab alignment to right

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.feedback.alignment'] = 'right';

2. Set feedback tab background colours and border colours

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.feedback.backgroundColor'] = '#ff9';
_weq['webengage.feedback.borderColor'] = '#f99';

3. Prepopulate email and keep it readonly, hide message, specific options for category drop-down

// Values int the category drop-down 'Like' & 'Question'
var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.feedback.formData'] = [
    {
        'name' : 'email',
        'value' : '_EMAIL_VALUE_',
        'mode' : 'readOnly'
    }, {
        'name' : 'message',
        'mode' : 'hidden'
    }, {
        'name' : 'category',
        'isMandatory' : false,          
        'value' : 'like',
        'options' : ['Like', 'Question'] // make sure you send right category lables
    }
];

Feedback Callbacks

CallbackDescriptionCallback data
onOpeninvoked on feedback form openObject
onCloseinvoked when feedback form is closedObject
onSubmitinvoked when a feedback is submittedObject

Feedback onOpen callback data (JSON)

{
        "licenseCode": "311c48b3",
        "type": "feedback",
        "activity": {
        "pageUrl": "http://webengage.net/publisher/feedback-configuration/fields/311c48b3",
        "pageTitle": "Feedback Configuration - WebEngage",
        "ip": "127.0.0.1",
        "city": "Mumbai",
        "country": "India",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
        "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Feedback onSubmit callback data (JSON)

{
    "id": "has7e2",
    "licenseCode": "311c48b3",
    "type": "feedback",
    "fields": [{
        "id": "1fcdjgf",
        "label": "Name",
        "type": "default",
        "value": {
            "@class": "name",
            "text": "John"
        }
    }, {
        "id": "ah1ihjd",
        "label": "Email",
        "type": "default",
        "value": {
            "@class": "email",
            "text": "[email protected]"
        }
    }, {
        "id": "cci1868",
        "label": "Category",
        "type": "default",
        "value": {
            "@class": "category",
            "text": "Suggestion"
        }
    }, {
        "id": "~78me196",
        "label": "Message",
        "type": "default",
        "value": {
            "@class": "message",
            "text": "Thank you very much for this awesome service!"
        }
    }, {
        "id": "~5d68amb",
        "label": "Attach a screenshot of this page",
        "type": "default",
        "value": {
            "@class": "snapshot",
            "thumbnailImageUrl": ""
        }
    }, {
        "id": "n283q0",
        "label": "Enter your mobile number",
        "type": "custom",
        "value": {
            "@class": "text",
            "text": "9988776655"
        }
    }, {
        "id": "pp3j84",
        "label": "Your Bio",
        "type": "custom",
        "value": {
            "@class": "text",
            "text": "I am an early beta user of this product."
        }
    }, {
        "id": "19jb68o",
        "label": "Which countries you have been to?",
        "type": "custom",
        "value": {
            "@class": "list",
            "values": ["US", "Mexico"]
        }
    }, {
        "id": "1cc6lks",
        "label": "Rate our website",
        "type": "custom",
        "value": {
            "@class": "matrix",
            "values": {
                "Experience": ["Good"],
                "Content": ["Good"],
                "Design": ["Poor"]
            }
        }
    }, {
        "id": "sht4k8",
        "label": "Upload your resume",
        "type": "custom",
        "value": {
            "@class": "file",
            "fileName": "android_sdk_developing.pdf",
            "fileSize": 1919972,
            "fileAccessUrl": "https://api.webengage.com/v1/download/feedback/response/ofq4jy",
            "fileType": "pdf"
        }
    }, {
        "id": "16qfkqk",
        "label": "What is your favourite color?",
        "type": "custom",
        "value": {
            "@class": "list",
            "values": ["Red"]
        }
    }],
    "activity": {
        "pageUrl": "http://webengage.net/publisher/feedback-configuration/fields/311c48b3",
        "pageTitle": "Feedback Configuration - WebEngage",
        "ip": "127.0.0.1",
        "city": "Mumbai",
        "country": "India",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
    "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Feedback onClose callback data (JSON)

On feedback close the callback data for close event handlers will the latest event's (Open or Submit) callback data that happened before close.

Lets say if you close feedback window after it opens the callback data for close event would same as the onOpen callback data as mentioned above.

{
        "licenseCode": "311c48b3",
        "type": "feedback",
        "activity": {
        "pageUrl": "http://webengage.net/publisher/feedback-configuration/fields/311c48b3",
        "pageTitle": "Feedback Configuration - WebEngage",
        "ip": "127.0.0.1",
        "city": "Mumbai",
        "country": "India",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
        "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Examples of using Feedback Callbacks

1. Close the feedback window in 5 second just after someone submits feedback.

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.enableCallbacks'] = true;
_weq['webengage.feedback.onSubmit'] = function () {
        var feedbackInstance = this;
        setTimeout(function(){
            feedbackInstance.close();
        }, 5000);
};

Feedback Methods

1. webengage.feedback.render

This method allows you to overwrite the dashboard settings. It also overwrites the settings provided in _weq in the widget code. This method accepts all the _weq feedback configuration properties and _weq callbacks.

NameTypeDescription
optionsObjectFeedback Configuration Properties & callbacks

Examples for Render Method

1. Show a feedback on click of a button

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.feedback.render({ 'showForm' : true });
    };
};

2. webengage.feedback.clear

Example of clear Method

1. Clear a feedback on click of a button

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.feedback.clear();
    };
};

Notification Settings

Notification Configuration Properties

PropertyTypeDescriptionDefault
notificationIdStringTo show a specific notification, specify the notificationIdnull
skipRulesBooleanIf set to true, targeting rules specified in the dashboard for the active notifications are not executed. Thus, all the active notifications, unless notificationId is specified, become eligible to be shownfalse
forcedRenderBooleanIf set to true, the clicked or closed notifications also become elgible to be shownfalse
delayNumberTime delay, in miliseconds, to show a survey on a page. It overrides the time delay specified in the dashboardnull
defaultRenderBooleanIf set to false, the eligible notification is not displayed by defaulttrue
customDataObjectSpecify your custom data for notification here in proper JSON format to submit along with every notification click. If not set then webengage.customData is referrednull
ruleDataObjectSpecify 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 Notification. If not specified webengage.ruleData is referednull
tokensObjectSpecify your tokens data here in proper JSON format. If not specified webengage.tokens is referednull
enableCallbacksBooleanIf set to true, will enable callbacks for all the notification eventsfalse

Examples of using Notification Properties

1. Delay a particular notification rendering

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.delay'] = 5;
_weq['webengage.notification.notificationId'] = _NOTIFICATION_ID_;

Note : If you have already set the time-delay in the notification rule while creating it, webengage.notification.delay will overwrite it.

2. Skip rules on a page for notifications

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.skipRules'] = true;

3. Custom rules - showing a "we are offline" notification every Sunday

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
var daysInWeek = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
_weq['webengage.notification.ruleData'] = {day : daysInWeek[new Date().getDay()]};

Note: In custom rules section, on the targeting page, you can use the "day" variable to create targeting rules. For example, if the day is "Sunday", display a notification on your contact page that your support team is currently offline.

Notification Callbacks

CallbackDescriptionCallback data
onOpeninvoked on notification openObject
onCloseinvoked when a notification is closedObject
onClickinvoked when a notification is clickedObject

Notification onOpen callback data (JSON)

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Checkout the new pricing",
    "event": "open",
    "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"
        },
    "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Notification onClick callback data (JSON)

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Checkout the new pricing",
    "event": "click",
    "actionLink": "http://webengage.com/pricing",
    "actionText": "Check out",
    "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"
        },
    "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Notification onClose callback data (JSON)

On notification close the callback data for close event handlers will the latest event's (Open or Click) callback data that happened before close.

Lets say if you close a notification after it opens the callback data for close event would same as the onOpen callback data as mentioned above.

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Checkout the new pricing",
    "event": "click",
    "actionLink": "http://webengage.com/pricing",
    "actionText": "Check out",
    "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"
        },
    "customData": {
                "userName" : [ "john" ],
                "gender" : [ "male" ],
                "customerType" : [ "Gold" ],
                "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Examples of using Notification Callbacks

1. Callback handler when a notification is closed

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.onClose'] = function () {
    var r=confirm("Do you realy want to miss this offer");
    if (r==false){
      return false;
    }
};

Notification Methods

1. webengage.notification.render

This method allows you to overwrite the dashboard settings. It also overwrites the settings provided in _weq in the widget code. This method accepts all the _weq notification configuration properties and _weq callbacks.

NameTypeDescription
optionsObjectNotification configuration properties callbacks

Examples of Render Method

1. Open a notification on click of a button
var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.defaultRender'] = false;
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.notification.render();
    };
};

2. Open a notification on page scroll (down)

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.defaultRender'] = false;
_weq['webengage.onReady'] = function () {
    var getScrollPercentage = function () {
        var documentHeight = $(document).height();
        var viewPortHeight = $(window).height();
        var verticlePageOffset = $(document).scrollTop();
        return Math.round(100* (viewPortHeight+verticlePageOffset)/documentHeight);
    }
    var notificationDisplayed = false;
    window.onscroll = function (event) {
        if (!notificationDisplayed && getScrollPercentage() >= 70) {
            webengage.notification.render({ notificationId : '_NOTIFICATION_ID_' }); // invoking webengage.notification.render with specific notification id
            notificationDisplayed = true;
        }
    }
};

Also, notice that we are calling webengage.notification.render by passing it notificationId option.

3. Passing Custom Data / Rule Data

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.notification.ruleData'] = { 'categoryCode' '_CATEGORY_CODE_', 'paidCustomer' : true };
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.notification.render({
            'customData' :  { 'userId' : '_USER_ID_', 'age' : _AGE_ }
        });
    };
};

4. Popping an alert onClose of a notification

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function(){
    document.getElementById("_BUTTON_ID_").onclick = function(){
        webengage.notification.render().onClose( function(){
            alert("You have closed the notification");
        });
    };
};

2. webengage.notification.clear

Clears rendered notification.

Examples of Clear Method

1. Clear a notification on click of a button

var _weq = _weq || {};
_weq['webengage.licenseCode'] = '_LICENSE_CODE_';
_weq['webengage.onReady'] = function () {
    document.getElementById("_BUTTON_ID_").onclick = function () {
        webengage.notification.clear();
    };
};