Legacy SDK v3

JavaScript API (Version 3.0)

The WebEngage JavaScript API provides interface to WebEngage JavaScript widget sitting on your website and thus allows you to customize its configuration and behaviour. Look at few examples mentioned below -

Overview

WebEngage JavaScript API has two main components. One is at the top widget level and other is at the individual product level.

Widget - Widget Level Customization - examples of using JavaScript API

  • Hide WebEngage widget on certain pages of your website
  • Load the entire widget after a certain time delay

Feedback - WebEngage Feedback - examples of using JavaScript API

  • Customize the style and alignment of the feedback tab
  • Show a different feedback form based on sections of your website
  • Pre-populate name and email in the feedback form for your signed-in users
  • Pass your own custom/business data (your user identifier) along with each feedback
  • many more..

Survey - WebEngage Survey - examples of using JavaScript API

  • Show a survey on click of a button
  • Show a survey when a page is scrolled down to the bottom
  • Show a survey for visitors who have spent more than 5 minutes on your website
  • Pass data for custom targeting rules
  • Pass your own custom/business data (your user identifier) along with survey response for tracking
  • many more..

Notification - WebEngage Notification - examples of using JavaScript API

  • Show a notification on click of a button
  • Show a notification when a page is scrolled down to the bottom
  • Show a notification with 50% chances of appearing on a page
  • Pass data for custom targeting rules
  • Pass your own custom/business data (your user identifier) along with survey response for tracking
  • many more..

Widget API

The API must be initialized before making any calls. You will need your WebEngage registered website's licenseCode to initialize the API. If you haven't registered your website, you can register here. On successful registration, you will be provided a one time integration code which you can place anywhere inside the website's html markup. The best place to put this code is right before the closing body tag </body>.

Loading And Initialization

The one time integration code will load and initialize the JavaScript API with the available initialization options.
Following is the default one time integration code snippet for example.

<script id="_webengage_script_tag" type="text/javascript">
    /**
   * You can define window.webengageWidgetInit to override code
   * that comes by default with the integration code.
   */
    window.webengageWidgetInit = window.webengageWidgetInit || function(){
        webengage.init( {
            licenseCode : '_LICENSE_CODE_'
        }).onReady(function() {
            webengage.render();
        });
    };
    (function(d){
    var _we = d.createElement('script');
    _we.type = 'text/javascript';
    _we.async = true;
    _we.src = (d.location.protocol == 'https:' ? 'https://ssl.widgets.webengage.com' : 'http://cdn.widgets.webengage.com') + "/js/widget/webengage-min-v-3.0.js";
    var _sNode = d.getElementById('_webengage_script_tag');
    _sNode.parentNode.insertBefore(_we, _sNode);
  })(document);
</script>

This code loads the API 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 load the API over the same protocol (HTTP or HTTPS) as the parent webpage.

The function assigned to window.webengageWidgetInit will run as soon as the API is loaded. All the widget initialization options should be passed in webengage.init . Any code, that you want to run after the API is loaded, should be placed within the webengage.onReady.

See the webengage.init documentation for a complete list of available initialization options.

Methods

webengage.init

The webengage.init function initializes the API with the passed initialization options.
Note: The API must be initialized atleast with the registered license code before making any API call against it.

Example Code:

webengage.init({
    // Specify license code of your domain
    licenseCode : '_LICENSE_CODE_'

    // Delay the API initialization by the time specified here in miliseconds.
    delay : '_TIME_IN_MILI_SEC_'
})

Parameters

Name

Type

Description

initOptions

Object

API Initialization options

Initialization Options

Property

Type

Description

Required

Default

licenseCode

String

Registered license code for the website. You can get it from your WebEngage dashboard if the website registered or register it here right now

Yes

null

delay

Number

Delays API initialization with the time specified here in miliseconds

No

0

webengage.onReady

The webengage.onReady function ensures the successful initialization of the API. The code that you would like to execute after the API initialization must go inside this function.

Default code:

webengage.onReady(function() {

    // This callback function is executed as soon as the API is initialized.
    // This is the default  implementation and it internally invokes rendering
    // of feedback tab, surveys and notification if applicable.
    webengage.render();

});

Parameters

Name

Type

Description

funcToCallOnReady

Function

Function to be executed on API ready

webengage.render

The webengage.render method internally invokes rendering of feedback tab, surveys and notification if applicable.
In case of any customization that you would like to do with the Feedback, Surveys or Notifications, there are separate APIs available for individual products - feedback, survey and notification.

See the feedback, survey and notification API documentation for the complete list of available customization options.

Examples

Hide WebEngage widget on certain pages of your website

window.webengageWidgetInit = window.webengageWidgetInit || function(){
    webengage.init( {
        licenseCode : '_LICENSE_CODE_'
    }).onReady(function() {
        var pageUrl = document.location.href;
        //hide widget on Terms and Services page
        if(pageUrl != 'http://www.mywebsite.com/terms'){
          webengage.render();
        }
    });
};

Load the entire widget 4 seconds after the page loads

window.webengageWidgetInit = window.webengageWidgetInit || function(){
    webengage.init( {
        licenseCode : '_LICENSE_CODE_',
        delay : 4000
    }).onReady(function() {
        webengage.render();
    });
};

Feedback API

The core object of the Feedback API is webengage.feedback. Using its API methods, one can render feedback tab with custom style, open the feedback form on click of your own button, render feedback forms based on the feedback category, pass custom data along with each feedback submitted and also allows you to remove the feedback tab if needed. Many more such use cases can be addressed using the below mentioned API methods.

Methods

webengage.feedback.render

This methods creates feedback tab. Also shows feedback form, if needed.

Parameters

Name

Type

Description

options

Object

Feedback customization options

Feedback Customization Options

Property

Type

Description

Default

feedbackButtonAlignment

String

Shows 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

feedbackButtonTextColor

String

Renders feedback tab text with the specified color. Specify here the hex code of the feedback tab text color you desired. For example pass in hex code #0000ff to display feedback tab text in blue color

As specified in feedback tab configuration

feedbackButtonBorderColor

String

Renders feedback tab with the specified border color

As specified in feedback tab configuration

feedbackButtonBackgroundColor

String

Renders feedback tab with the specified background color

As specified in feedback tab configuration

defaultFeedbackCategory

Renders the feedback form based on the feedback category specified here

As specified in feedback category configuration

showAllFeedbackCategories

Boolean

If set to true Feedback API renders feedback form with feedback category dropdown menu to let the end users to submit contextual feedbacks. If set to false, Feedback API renders feedback form based on the default feedback category specified without any feedback category dropdown menu

true

data

Object

Specify your custom data here in proper JSON format to be submitted along with feedback

null

webengage.feedback.clear

This function removes the feedback tab and form, if shown, from the webpage. It takes no parameters.

Examples

Listing below few common usages of WebEngage Feedback JavaScript API

Customize the style and alignment of the feedback tab

Makes feedback tab appear on the left hand side of the page with colors defined in the arguments.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        //call default renderers for survey and notification
        webengage.survey.render();
        webengage.notification.render();

        //render the feedback tab using following colors
        webengage.feedback.render({
            feedbackButtonAlignment:"left",
            feedbackButtonTextColor:"#FFE4B5",
            feedbackButtonBackgroundColor:"#DEB887",
            feedbackButtonBorderColor:"#8B4513"
        });
    });
// ]]>
</script>

Show a feedback form on click of a button on your page

Instead of using the default feedback tab, you can make the feedback form appear on click of a button/link on your webpage.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        //call default renderers for survey and notification
        webengage.survey.render();
        webengage.notification.render();
  $("button#help-support").click(function(){
    //render the feedback tab as well as form
    webengage.feedback.render({
      showFeedbackForm:true //opens the form
    });
        });
    });
// ]]>
</script>

Show a different feedback form based on sections of your website

One can pre-populate feedback category and show the feedback form loaded with its custom fields. On different section of your website, you can pass default category -

<script type="text/javascript">// <![CDATA[
webengage.onReady(function(){
  //render the feedback (tab), survey (if any) and notification (if any) by default
  webengage.render();

  //Demo 1: bind the click event of sales-related-query button
  $("button#sales-related-query").click(function(){
    //render the feedback tab
    webengage.feedback.render({
      feedbackButtonTextColor:"#FFFFFF",
      feedbackButtonBackgroundColor:"#87CEEB",
      feedbackButtonBorderColor:"#191970",
      defaultFeedbackCategory:"Sales/pricing related query",
      showAllFeedbackCategories:true,
      showFeedbackForm:true //open the tab
    });
  });

  //Demo 2: bind the click event of apply-for-job button
  $("button#apply-for-job").click(function(){
    webengage.feedback.render({
      feedbackButtonTextColor:"#FFE4B5",
      feedbackButtonBackgroundColor:"#DEB887",
      feedbackButtonBorderColor:"#8B4513",
      defaultFeedbackCategory:"Jobs and hiring",
      showAllFeedbackCategories:false, //don't show the category drop-down
      showFeedbackForm:true
    });
  });
});
//]]></script>

Pre-populate name and email in the feedback form for your signed-in users

<script type="text/javascript">// <![CDATA[
webengage.onReady(function(){
        // call default renderers for survey and notification
        webengage.survey.render();
        webengage.notification.render();

        // pass name and email fields to feedback.
        // The keys used in the data JSON object should match exactly with your feedback field labels
        webengage.feedback.render({
            data: {
                "Name"  : "<?php echo $userName; ?>",
                "Email" : "<?php echo $userEmail; ?>"
            }
        });
    });
// ]]></script>

Pass your own custom/business data (your user identifier) along with each feedback

<script type="text/javascript">// <![CDATA[
webengage.onReady(function(){
        //call default renderers for survey and notification
        webengage.survey.render();
        webengage.notification.render();

        //render the feedback tab using following colors
        webengage.feedback.render({
            data: {
                userId: <?php echo $userId; ?>,
                category: "<?php echo $userCategory; ?>"
            }
        });
});
// ]]></script>

Survey API

The core object of the Survey API is webengage.survey. Using its API methods, one can show a specific survey on click of a button, change survey theme real-time, pass custom data along with each survey response submitted, pass rules data for custom targeting (e.g. shopping cart abandonment) and one can use custom logic to show a survey.

Methods

webengage.survey.render

This method checks the applicable survey on a webpage and shows as per defined configuration - time delay, theme and alignment. The method provides hooks and options to override the default behaviour. One can

  • pop-up a specific survey
  • skip the rules defined in the dashboard for a survey
  • show a survey irrespective whether it has been taken or closed by the site's visitor
  • render a survey after a time delay different than the configured one
  • pass custom/business data along with each survey got submitted
  • pass rule data for custom rules specified in targeting

Parameters

Name

Type

Description

options

Object

Survey customization options

Survey Customization Options

Property

Type

Description

Default

surveyId

String

Renders the survey with the specified surveyId. Checks for its applicability based on the rules defined for this survey

Applicability check is performed based on rules defined

skipRuleExecution

Boolean

If set to true, rules defined for the survey are skipped

false

showAllClosedAndTakenSurveys

Boolean

If set to true, it shows surveys that have already been taken or closed by the website visitor

false

delay

Number

Delays the survey rendering by the time specified here in miliseconds. It overrides the delay time configured in the targeting rules section for that survey

As specified in the survey rules configuration

data

Object

Specify your custom data in proper JSON format to be submitted along with individual survey response

null

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

webengage.survey.clear

This function can be used to remove the survey pop-up window from a Webpage. It takes no parameters.

Examples

Listing below few common usages of WebEngage Survey JavaScript API

Show a survey on click of a button

Show a survey as pop-up on your website on click of a button/link

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        //render the feedback (tab) and survey (if any) by default
        webengage.render();

        //Take Survey: bind the click event of a button to trigger a lead generation survey
        document.getElementById("take-survey").onclick = function(){
            //call the survey renderer
            webengage.survey.render({

                //the survey to invoke
                surveyId:"_LEAD_GENERATION_SURVEY_ID_",

                //ignore targeting-rules for the survey
                skipRuleExecution:true,

                //once a visitor has taken a survey or closed it on your site
                //it doesn't appear again for the same visitor.
                //to make this survey appear irrespective, we can override this behavior by setting "true"
                showAllClosedAndTakenSurveys:true,

                //to keep the user experience intact on your site, WebEngage
                //let's you time-delay the survey. this works great in
                //auto mode. however, while using the API, you'd want the survey
                //to immediately pop upon some user action.
                // "delay" is your friend
                delay:0
            });
        };
    });
//]]></script>

Show a survey on custom/business rules

To show a survey only to repeat customers who signs in to your website after 2 months, you just need to pass these 2 metrics and create a custom rule in the Targeting Rules section of the survey.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.notification.render();

        //pass business data for custom rules set in targeting section
        webengage.survey.render({
            ruleData: {
                "daysAfterSignedIn" : <?php echo $daysAfterUserLoggedIn; ?>,
                "customerType" : "<?php echo $customerGroup; ?>"
            }               
        });
    });
// ]]></script>

Pass your custom/business data along with individual survey response

You can pass your own business data to identify a survey response and tie it with your own database user. Moreover, you can pass more context to understand user behaviour on your site.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.notification.render();

        //pass business data for custom rules set in targeting section
        webengage.survey.render({
            data: {
            'userId' : <?php echo $myUserId; ?>,
            'customerType' : '<?php echo $customerGroup; ?>',
            'searchQuery' : '<?php echo ".$_REQUEST['term']." ?>'
            }               
        });
    });
// ]]></script>

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.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.notification.render();

        //set custom scope for surveys
        webengage.survey.render({
            'scope' : '_USER_SESSION_ID_',
            'scopeType' : 'session'
        });
    });
// ]]></script>

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.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.notification.render();

        var today = new Date();
        //set custom scope for surveys
        webengage.survey.render({
            'scope' : {
                'scope' : (today.getDate()+"-"+today.getMonth()+"-"+today.getYear()),
                'scopeType' : 'session',
                'surveyIds' : ["~29aj48l"]
            }
        });
    });
// ]]></script>

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

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.notification.render();

        //set custom scope for surveys
        webengage.survey.render({
            'scope' : '_USER_EMAIL_',
            'scopeType' : 'global'
        });
    });
// ]]></script>

Notification API

The core object of the Notification API is webengage.notification. Using its API methods, one can show a specific notificaton on click of a button, change notification theme real-time, pass custom data along with each notification click that gets recorded, pass rules data for custom targeting (e.g. shopping cart abandonment) and one can use custom logic to show a notification.

Methods

webengage.notification.render

This method checks the applicable notification on a webpage and shows as per defined configuration - time delay, theme and alignment. The method provides hooks and options to override the default behaviour. One can

  • pop a specific notification
  • skip the rules defined in the dashboard for a notification
  • render a notification after a time delay different than the configured one
  • pass custom/business data along with each notification click
  • pass rule data for custom rules specified in targeting

Parameters

Name

Type

Description

options

Object

Notification customization options

Notification Customization Options

Property

Type

Description

Default

notificationId

String

Renders the notification with the specified notificationId. Checks for its applicability based on the rules defined for this notification

Applicability check is performed based on rules defined

skipRuleExecution

Boolean

If set to true, rules defined for the notification are skipped

false

delay

Number

Delays the notification rendering by the time specified here in miliseconds. It overrides the delay time configured in the targeting rules section for that notification

As specified in the notification rules configuration

data

Object

Specify your custom data in proper JSON format to be recorded along with each notification click

null

webengage.notification.clear

This function removes the notification pop-up window from a Webpage. It takes no parameters.

Examples

Listing below few common usages of WebEngage Notification JavaScript API

Show a notification on click of a button

Pop a notification on your website on click of a button/link

<script type="text/javascript">// <![CDATA[
webengage.onReady(function(){
  //render the feedback (tab) and notification (if any) by default
  webengage.render();

  //Demo 5: bind the click event of a button to trigger a promotional notification
  document.getElementById("take-lead-notification").onclick = function(){
    //call the notification renderer
    webengage.notification.render({
      //the notification to invoke
      notificationId:"_PROMOTION_NOTIFICATION_ID_",
      //don't worry about targeting-rules for the notification
      //more on what is targeting and why should you use it -
      // http://webengage.com/notification
      skipRuleExecution:true,
      //to keep the user experience intact on your site, WebEngage
      //let's you time-delay the notification. this works great in
      //auto mode. however, while using the API, you'd want the notification
      //to immediately pop upon some user action.
      // "delay" is your friend
      delay:0
    });
  };

  //Demo 6: bind the click event to a button button to pop a system alert notification
  document.getElementById("take-notification").onclick = function(){
    //call the notification renderer
    webengage.notification.render({
      notificationId:"_SYSTEM_ALERT_NOTIFICATION_ID_",
      skipRuleExecution:true,
      delay:0
    });
  };
});
// ]]></script>

Show a notification with 50% chances of appearing on a page

Show a notification with 50% probability of it appearing on a page

<script type="text/javascript">// <![CDATA[
webengage.onReady(function(){
  //render the feedback (tab) and notification (if any) by default
  webengage.feedback.render();
  webengage.survey.render();
        // range (1 - 100) specifies probability of displaying notification
        var percentChances = 50;
  var randomNumber = Math.floor((Math.random()*(100/percentChances)));
  if (randomNumber === 0) {
    webengage.notification.render();
  }
});
// ]]></script>

Pass your own custom/business data (your user identifier) along with survey response for tracking

You can pass your own business data to identify a visitor who clicked on the notification. Along with your user identifier, you can pass more context to understand user behaviour on your site.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.survey.render();
        //pass business data for custom rules set in targeting section
        webengage.notification.render({
            data: {
            'userId' : <?php echo $myUserId; ?>,
            'customerType' : '<?php echo $customerGroup; ?>',
            'searchQuery' : '<?php echo ".$_REQUEST['term']." ?>'
            }
        });
    });
// ]]></script>

Pass data for custom targeting rules

To show a notification with discount offer to customers who have more than 2 items in the cart worth more than $100 and haven't yet made a purchase after spending 5 minutes on the page, you just need to pass these two metrics and create a custom rule in the Targeting Rules section of the notification.

<script type="text/javascript">// <![CDATA[
    webengage.onReady(function(){
        webengage.feedback.render();
        webengage.survey.render();

        //pass business data for custom rules set in targeting section
        webengage.notification.render({
            ruleData: {
                "itemsInCart" : <?php echo $itemsInCart; ?>,
                "cartAmount" : <?php echo $totalCartValue; ?>
            }
        });
    });
// ]]></script>

Did this page help you?