Web SDK Integration

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

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

info	Note Required step for all web modules

Data Center

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

Data Center	Dashboard host
dc_1	dashboard-01.moengage.com
dc_2	dashboard-02.moengage.com
dc_3	dashboard-03.moengage.com
dc_4	dashboard-04.moengage.com

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.

TEST Integration

To integrate into the test environment:

Insert the following code in the <head> tag of every page that requires tracking.
Replace "APP ID" available in the settings page of MoEngage Dashboard.
Navigate to `Dashboard --> Settings --> App --> General` and copy the APP ID.
Replace "DC" with the data center form the above table

debug_logs: 1

<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.
      
!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+"/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:

Insert the following code in the <head> tag of every page that requires tracking.
Replace "APP ID" available in the settings page of MoEngage Dashboard.
Navigate to `Dashboard --> Settings --> App --> General` and copy the APP ID.
Replace "DC" with the data center form the above table

debug_logs: 0

<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.
      
!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+"/moe_webSdk.min.latest.js","Moengage");

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

Using NPM

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

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:

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:

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:

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:

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

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:

https://cdn.moengage.com/

style-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

Reach out to us directly from your MoEngage Dashbaord -> Need Help? -> Contact Support or send an email to support@moengage.com.