1. Developer Guide
  2. Web SDK
  3. Web SDK Integration
  4. Basic Integration
Web SDK Integration

Follow these steps to integrate MoEngage Web SDK either in the test or in the production environment:

  1. Perform the web SDK integration using one of the following:
    1. On your website using MoEngage CDN
    2. NPM
    3. Google Tag Manager(GTM)
    4. Single Page App (SPA) Support
    5. Configure and Integrate AMP Web Push
    6. Flutter SDK
    7. Shopify App
  2. Specify the MoEngage DataCenter for web SDK data collection
  3. Enable Whitelisting
info

Note

Required step for all web modules

Method 1: MoEngage CDN

TEST Integration

Data Center

Following details of the different data centers you need to set based on the dashboard hosts

Dashboard host Data Center

dashboard-01.moengage.com

dc_1

dashboard-02.moengage.com

dc_2

dashboard-03.moengage.com

dc_3

dashboard-04.moengage.com

dc_4

dashboard-06.moengage.com

dc_6

Keep the proper Data center handy as it will be used below for integration purpose.

MoEngage recommends that you perform the integration in the test environment first and then integrate it into the production or live environment.

To integrate into the test environment:

  1. Insert the following code in the <head> tag of every page that requires tracking.
  2. Replace "APP ID" available in the settings page of MoEngage Dashboard.
    Navigate to `Dashboard --> Settings --> App --> General` and copy the APP ID.
  3. Replace the value of sdkVersion with the version of Web SDK you intend to use. It is recommended to use the format x (major)
  4. Replace "DC" with the data center form the above table.

debug_logs: 1

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{WorkspaceID}"; // Replace "WorkspaceID" available in the settings page of MoEngage Dashboard.
var sdkVersion = "2"; // Replace this value with the version of Web SDK that you intend to use. It is recommended to use the format x (major)
      
!function(e,n,i,t,a,r,o,d){if(!moeDataCenter||!moeDataCenter.match(/^dc_[0-9]+$/gm))return console.error("Data center has not been passed correctly. Please follow the SDK installation instruction carefully.");var s=e[a]=e[a]||[];if(s.invoked=0,s.initialised>0||s.invoked>0)return console.error("MoEngage Web SDK initialised multiple times. Please integrate the Web SDK only once!"),!1;e.moengage_object=a;var l={},g=function n(i){return function(){for(var n=arguments.length,t=Array(n),a=0;a<n;a++)t[a]=arguments[a];(e.moengage_q=e.moengage_q||[]).push({f:i,a:t})}},u=["track_event","add_user_attribute","add_first_name","add_last_name","add_email","add_mobile","add_user_name","add_gender","add_birthday","destroy_session","add_unique_user_id","update_unique_user_id","moe_events","call_web_push","track","location_type_attribute"],m={onsite:["getData","registerCallback"]};for(var c in u)l[u[c]]=g(u[c]);for(var v in m)for(var f in m[v])null==l[v]&&(l[v]={}),l[v][m[v][f]]=g(v+"."+m[v][f]);r=n.createElement(i),o=n.getElementsByTagName("head")[0],r.async=1,r.src=t,o.appendChild(r),e.moe=e.moe||function(){return(s.invoked=s.invoked+1,s.invoked>1)?(console.error("MoEngage Web SDK initialised multiple times. Please integrate the Web SDK only once!"),!1):(d=arguments.length<=0?void 0:arguments[0],l)},r.addEventListener("load",function(){if(d)return e[a]=e.moe(d),e[a].initialised=e[a].initialised+1||1,!0}),r.addEventListener("error",function(){return console.error("Moengage Web SDK loading failed."),!1})}(window,document,"script","https://cdn.moengage.com/release/"+moeDataCenter+"/versions/"+sdkVersion+"/moe_webSdk.min.latest.js","Moengage");

Moengage = moe({
  app_id: moeAppID,
  debug_logs: 1
});
</script>

PRODUCTION or LIVE Integration

To integrate into the production or live environment:

  1. Insert the following code in the <head> tag of every page that requires tracking.
  2. Replace "APP ID" available in the settings page of MoEngage Dashboard.
    Navigate to `Dashboard --> Settings --> App --> General` and copy the APP ID.
  3. Replace the value of sdkVersion with the version of Web SDK you intend to use. It is recommended to use the format x (major)
  4. Replace "DC" with the data center form the above table

debug_logs: 0

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{WorkspaceID}"; // Replace "WorkspaceID" available in the settings page of MoEngage Dashboard.
var sdkVersion = "2"; // Replace this value with the version of Web SDK that you intend to use. It is recommended to use the format x (major)
      
!function(e,n,i,t,a,r,o,d){if(!moeDataCenter||!moeDataCenter.match(/^dc_[0-9]+$/gm))return console.error("Data center has not been passed correctly. Please follow the SDK installation instruction carefully.");var s=e[a]=e[a]||[];if(s.invoked=0,s.initialised>0||s.invoked>0)return console.error("MoEngage Web SDK initialised multiple times. Please integrate the Web SDK only once!"),!1;e.moengage_object=a;var l={},g=function n(i){return function(){for(var n=arguments.length,t=Array(n),a=0;a<n;a++)t[a]=arguments[a];(e.moengage_q=e.moengage_q||[]).push({f:i,a:t})}},u=["track_event","add_user_attribute","add_first_name","add_last_name","add_email","add_mobile","add_user_name","add_gender","add_birthday","destroy_session","add_unique_user_id","update_unique_user_id","moe_events","call_web_push","track","location_type_attribute"],m={onsite:["getData","registerCallback"]};for(var c in u)l[u[c]]=g(u[c]);for(var v in m)for(var f in m[v])null==l[v]&&(l[v]={}),l[v][m[v][f]]=g(v+"."+m[v][f]);r=n.createElement(i),o=n.getElementsByTagName("head")[0],r.async=1,r.src=t,o.appendChild(r),e.moe=e.moe||function(){return(s.invoked=s.invoked+1,s.invoked>1)?(console.error("MoEngage Web SDK initialised multiple times. Please integrate the Web SDK only once!"),!1):(d=arguments.length<=0?void 0:arguments[0],l)},r.addEventListener("load",function(){if(d)return e[a]=e.moe(d),e[a].initialised=e[a].initialised+1||1,!0}),r.addEventListener("error",function(){return console.error("Moengage Web SDK loading failed."),!1})}(window,document,"script","https://cdn.moengage.com/release/"+moeDataCenter+"/versions/"+sdkVersion+"/moe_webSdk.min.latest.js","Moengage");

Moengage = moe({
  app_id: moeAppID,
  debug_logs: 0
});
</script>

Upgrading the SDK

When you reference the MoEngage Web SDK from our content delivery network, for example, https://cdn.moengage.com/release/{DC}/versions/{sdkVersion}/moe_webSdk.min.latest.js where sdkVersion = x (using sdkVersion = x, i.e. fixing version only till major release is our default integration recommendation), your users will receive new features and bug fixes automatically when they refresh your site.

However, when we release major changes, we require you to upgrade the MoEngage Web SDK manually to ensure that nothing in your integration will be impacted by breaking changes.

You can keep up-to-date with our latest release following our changelog for a full accounting of our Web SDK release history. To upgrade the MoEngage Web SDK:

  • Update the MoEngage library version by changing value of sdkVersion in the integration script.
  • If you have web push integrated, update version in the serviceworker cdn url in the service worker file on your site - by default, this is located at /serviceworker.js at your site’s root directory, but the location may be customized in some integrations. importScripts("https://cdn.moengage.com/release/{DC}/versions/[old-version-number]/serviceworker_cdn.min.latest.js");
  • If you have web personalisation integrated, update the version in the web personalisation script- https://cdn.moengage.com/release/{DC}/versions/[old-version-number]/moe_webSdk_webp.min.latest.js?app_id={workspace-id}
warning

Warning

These 3 integrations must be updated with the same version number for proper functionality. In case you are using NPM, use the version number of @moengage/web-sdk dependency that is in your package.json file.

Method 2: Using NPM

If your site uses NPM or Yarn package managers, you can add the Moengage NPM package  as a dependency.

Add MoEngage NPM Package
npm install --save @moengage/web-sdk
# or, using yarn:
# yarn add @moengage/web-sdk

Once installed, you can import or require the library in the typical fashion:

JavaScript
import moengage from "@moengage/web-sdk";

// or, using `require`

const moengage = require("@moengage/web-sdk");

Then, initialize it by passing the configurations in all the pages before using it:

JavaScript
moengage.initialize({app_id: 'XXXXXXXXXXXXXXXX'});

You can pass any configuration here. For example, if you want to change the data center, then pass it as shown in the following snippet:

JavaScript
moengage.initialize({app_id: 'XXXXXXXXXXXXXXXX', cluster: 'DC_2'});

After that, you can use any method of the Moengage SDK, as shown in the snippet below:

JavaScript
moengage.add_email('abc@xyz.com')

 

info

Note

If you wish to always use the latest version of the Web SDK (instead of the version of @moengage/web-sdk mentioned in your package manager), pass the property useLatest with value set to true in the configuration:

moengage.initialize({app_id: 'XXXXXXXXXXXXXXXX', cluster: 'DC_2', useLatest: true});
info

Note

Use the version of Web SDK that you intend by altering the version of @moengage/web-sdk dependency in your package manager. More information on how to use specific version or range of versions can be found here.

Whitelisting URLs

info

Note

Optional step for all web modules

If your website is configured to block the external endpoints, then all the network calls to MoEngage fails.
Ensure that you whitelist the following endpoints for smooth integration.

script-src:

image-src:

connect-src:

frame-src:

style-src:

font-src:

You will get the error Refused to connect to `https://***.moengage.com/****` because it violates the following Content Security Policy directive. if you do not whitelist the URLs.

For more information, refer to Content Security Policy.

Troubleshooting

Not able to debug SDK in the Test environment.

Check that the debug_logs are set to 1 while initializing the MoEngage SDK. For more information, refer to the sample code.

Logs are showing in the console of the browser in live applications.

Check that the debug_logs are set to 0 while initializing the MoEngage SDK.

What is difference between TEST & LIVE environment?

MoEngage Account provides you an option to test your integration in a staging/debug environment which we refer to as TEST environment. LIVE environment is meant to contain the data about your actual users/customers from your live website.
MoEngage Web SDK uses a parameter debug_logs: 1 to detect that you are integrating in TEST environment. When you decide to take your website LIVE, just pass the parameter debug_logs: 0 and all data about your actual users would start appearing in LIVE environment

To contact the MoEngage Support team, you can raise a ticket through the Support Web Form within the MoEngage dashboard. For more information, refer here.
 

Previous

Next

Was this article helpful?
15 out of 29 found this helpful

How can we improve this article?