Callbacks

Callbacks are useful for understanding the lifecycle stages of WebEngage messages. All WebEngage callbacks are called on the main thread.

New Session Started

This callback is invoked when a new session is started by our web SDK.

webengage.onSessionStarted(function(){
    //CALLBACK LOGIC GOES HERE
})

On-site Notification Callbacks

Notification Opened

This callback is invoked when the on-site notification is opened.

webengage.notification.onOpen(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Check out the new pricing",
    "event": "open",
    "activity": {
            "pageUrl": "http://example.com/",
            "pageTitle": "Example Title",
            "referrer": "",
            "browser": "Chrome",
            "version": 27,
            "OS": "Windows",
            "country": "United States",
            "region": "Texas",
            "city": "Dallas",
            "ip": "127.0.0.1"
        },
    "customData": {
            "userName" : [ "johndoe" ],
            "gender" : [ "male" ],
            "customerType" : [ "Gold" ],
            "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Notification closed

This callback is invoked when the on-site notification is closed.

webengage.notification.onClose(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Checkout the new pricing",
    "event": "click",
    "actionLink": "http://example.com/pricing",
    "actionText": "Check out",
    "activity": {
            "pageUrl": "http://example.com/",
            "pageTitle": "Example Title",
            "referrer": "",
            "browser": "Chrome",
            "version": 27,
            "OS": "Windows",
            "country": "United States",
            "region": "Texas",
            "city": "Dallas",
            "ip": "127.0.0.1"
        },
    "customData": {
            "userName" : [ "johndoe" ],
            "gender" : [ "male" ],
            "customerType" : [ "Gold" ],
            "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that notification.

Notification Clicked

webengage.notification.onClick(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "notificationId": "173049892",
    "licenseCode": "311c48b3",
    "type": "notification",
    "title": "Checkout the new pricing",
    "event": "click",
    "actionLink": "http://example.com/pricing",
    "actionText": "Check out",
    "activity": {
            "pageUrl": "http://example.com/",
            "pageTitle": "Example Title",
            "referrer": "",
            "browser": "Chrome",
            "version": 27,
            "OS": "Windows",
            "country": "United States",
            "region": "Texas",
            "city": "Dallas",
            "ip": "127.0.0.1"
        },
    "customData": {
            "userName" : [ "johndoe" ],
            "gender" : [ "male" ],
            "customerType" : [ "Gold" ],
            "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

On-site Survey Callbacks

Survey Opened

This callback is invoked when the on-site survey is opened.

webengage.survey.onOpen(function (data) {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "surveyId": "~5g1c4fd",
    "licenseCode": "311c48b3",
    "activity": {
        "pageUrl": "http://example.com/",
        "pageTitle": "Example Title",
        "referrer": "",
        "browser": "Chrome",
        "version": 27,
        "OS": "Windows",
        "country": "United States",
        "region": "Texas",
        "city": "Dallas",
        "ip": "127.0.0.1"
    },
    "type": "survey",
    "title": "Survey #1",
    "totalQuestions": 6,
    "customData": {
        "userName" : [ "johndoe" ],
        "gender" : [ "male" ],
        "customerType" : [ "Gold" ],
        "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
    }
}

Survey Closed

This callback is invoked when the on-site survey is closed.

webengage.survey.onClose(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "surveyId": "~5g1c4fd",
    "licenseCode": "311c48b3",
    "activity": {
        "pageUrl": "http://example.com/",
        "pageTitle": "Example Title",
        "referrer": "",
        "browser": "Chrome",
        "version": 27,
        "OS": "Windows",
        "country": "United States",
        "region": "Texas",
        "city": "Dallas",
        "ip": "127.0.0.1"
    },
    "type": "survey",
    "title": "Survey #1",
    "totalQuestions": 6,
    "customData": {
        "userName" : [ "johndoe" ],
        "gender" : [ "male" ],
        "customerType" : [ "Gold" ],
        "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
    }
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that survey.

Survey Submit

This callback is invoked when a question is answered.

webengage.survey.onSubmit(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "surveyId": "~5g1c4fd",
    "licenseCode": "311c48b3",
    "activity": {
        "pageUrl": "http://example.com/",
        "pageTitle": "Example Title",
        "referrer": "",
        "browser": "Chrome",
        "version": 27,
        "OS": "Windows",
        "country": "United States",
        "region": "Texas",
        "city": "Dallas",
        "ip": "127.0.0.1"
    },
    "type": "survey",
    "title": "Survey #1",
    "totalQuestions": 6,
    "customData": {
        "userName" : [ "johndoe" ],
        "gender" : [ "male" ],
        "customerType" : [ "Gold" ],
        "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
    },
    "questionResponses": [{
        "questionId": "~1fstl7a",
        "questionText": "What is your favourite color?",
        "value": {
                "@class": "list",
                "values": ["Red"]
        }
    }]
}

Survey Complete

This callback is invoked when the on-site survey is completed.

webengage.survey.onComplete(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
    "surveyId": "~5g1c4fd",
    "licenseCode": "311c48b3",
    "activity": {
        "pageUrl": "http://example.com/",
        "pageTitle": "Example Title",
        "referrer": "",
        "browser": "Chrome",
        "version": 27,
        "OS": "Windows",
        "country": "United States",
        "region": "Texas",
        "city": "Dallas",
        "ip": "127.0.0.1"
    },
    "type": "survey",
    "title": "Survey #1",
    "totalQuestions": 6,
    "customData": {
        "userName" : [ "johndoe" ],
        "gender" : [ "male" ],
        "customerType" : [ "Gold" ],
        "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
    },
    "questionResponses": [
    {
        "questionId": "~1fstl7a",
        "questionText": "Your name?",
        "value": {
            "@class": "map",
            "values": {
                "First name": "John",
                "Last name": "Doe"
            }
        }
    },
    {
        "questionId": "~1asf233",
        "questionText": "Enter your mobile number?",
        "value": {
            "@class": "text",
            "text": "+14155552671"
        }
    },
    {
        "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 our website",
        "value": {
            "@class" : "matrix",
            "values" : {
                "Experience" : [ "Good" ],
                "Content" : [ "Good" ],
                "Design" : [ "Poor" ]
            }
        }
    },
    {
        "questionId": "sht4k8",
        "questionText": "Upload your resume",
        "value": {
            "@class" : "file",
            "fileName" : "john_doe_resume.pdf",
            "fileSize" : 1919972,
            "fileAccessUrl" : "https://api.webengage.com/v1/download/feedback/response/ofq4jy",
            "fileType" : "pdf"
        }
    }]
}

Usage Examples

  1. Close survey after response of a particular question is submitted
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;
            }
        }
    }
});
  1. Redirect a user on survey completion
webengage.survey.onComplete(function () {
    window.location.href='/newletter/subscribe.html';
});

On-site Feedback Callbacks (Deprecated)

Feedback Opened

This callback is invoked when the on-site feedback widget is opened.

webengage.feedback.onOpen(function (data) {
       //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
        "licenseCode": "311c48b3",
        "type": "feedback",
        "activity": {
        "pageUrl": "http://example.com/page",
        "pageTitle": "Example Title",
        "ip": "127.0.0.1",
        "city": "Dallas",
        "country": "United States",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
        "customData": {
            "userName" : [ "johndoe" ],
            "gender" : [ "male" ],
            "customerType" : [ "Gold" ],
            "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

Feedback Closed

This callback is invoked when the on-site feedback widget is closed.

webengage.feedback.onClose(function (data) {
       //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
        "licenseCode": "311c48b3",
        "type": "feedback",
        "activity": {
        "pageUrl": "http://example.com/page",
        "pageTitle": "Example Title",
        "ip": "127.0.0.1",
        "city": "Dallas",
        "country": "United States",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
        "customData": {
            "userName" : [ "johndoe" ],
            "gender" : [ "male" ],
            "customerType" : [ "Gold" ],
            "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
        }
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that feedback.

Feedback Submitted

This callback is invoked when the on-site feedback is submitted.

webengage.feedback.onSubmit(function (data) {
        //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
    "id": "has7e2",
    "licenseCode": "311c48b3",
    "type": "feedback",
    "fields": [{
        "id": "1fcdjgf",
        "label": "Name",
        "type": "default",
        "value": {
            "@class": "name",
            "text": "John Doe"
        }
    }, {
        "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": "+14155552671"
        }
    }, {
        "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": "john_doe_resume.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://example.com/page",
        "pageTitle": "Example Title",
        "ip": "127.0.0.1",
        "city": "Dallas",
        "country": "United States",
        "browser": "Firefox",
        "browserVersion": "18",
        "platform": "Linux",
        "activityOn": "2013-02-11T08:09+0000"
    },
    "customData": {
        "userName" : [ "johndoe" ],
        "gender" : [ "male" ],
        "customerType" : [ "Gold" ],
        "jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
    }
}

Usage Examples

  1. Close the feedback window 5 seconds after user submits feedback
webengage.feedback.onSubmit(function (data) {
        var feedbackInstance = this;
        setTimeout(function(){
            feedbackInstance.close();
        }, 5000);
});

Web Push Callbacks

Web Push Notification Permission Prompt Viewed

For both 1-step opt-in and 2-step opt-in, this callback is invoked when browser prompts the notification permission to the user.

webengage.options('webpush.onWindowViewed', function () {
// Callback logic goes here.
});

Web Push Notification Permission Granted

For 1-step opt-in, this callback is invoked when the user grants permission for Web Push. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user grants permission for Web Push.

webengage.options('webpush.onWindowAllowed', function () {
// Callback logic goes here.
});

Web Push Notification Permission Denied

For 1-step opt-in, this callback is invoked when the user denies permission for Web Push. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user denies permission for Web Push.

webengage.options('webpush.onWindowDenied', function () {
// Callback logic goes here.
});

Web Push Notification Permission Granted First Time

For 1-step opt-in, this callback is invoked when the user grants permission for Web Push for the first time. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user grants permission for Web Push for the first time.

webengage.options('webpush.onPushRegistered', function () {
// Callback logic goes here.
});

Web Push Notification Permission Revoked

For 1-step opt-in, this callback is invoked when the user revokes permission for Web Push after having granted it before. This callback is not available for 2-step opt-in.

webengage.options('webpush.onPushUnregistered', function () {
// Callback logic goes here.
});

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!