Skip to main content

​
Overview

You can integrate the Web SDK for any of the supported frameworks (CDN, NPM, GTM, SPA, AMP, Flutter, and Shopify) using one of the following two methods:
  • Script-based Initialization (Recommended): Use the form-based interface to generate a validated code snippet or access module-specific configurations. For more information, refer to Script-based Initialization (Recommended).
  • Manual Integration: Manually configure the SDK parameters and initialization code. For more information, refer to Option 2: Manual Integration.
You must have your Workspace ID (App ID) and Data Center. You can retrieve these details by navigating to Settings > App > General on the Dashboard.
To ensure a reliable and streamlined setup, we recommend using the Script-based initialization method. This method generates a validated JavaScript snippet, eliminating potential syntax errors and automatically including required flags based on the application type.
  • Workspace Details: Ensure you have your Workspace ID (App ID) and Data Center (found in Settings > App > General on the Dashboard).
  • Service Worker (For Web Push): If enabling Web Push, create a file named serviceworker.js in your root directory.
  • Whitelisting (CSP): If your site uses a Content Security Policy, whitelist the necessary MoEngage URLs. For more information, refer here.
Follow these steps to generate your initialization script:
  1. Navigate to the Web SDK Initialization Website.
  2. Configure the values based on your application requirements. Refer to the Configuration Parameters table below for detailed descriptions of each field.
  3. Click Generate Code at the bottom of the form to create your validated JavaScript snippet.
  4. Implement the Generated Code: Copy the code snippets displayed by the tool and paste them into your project as follows:
    • Update Service Worker (If Web Push Enabled): Add the generated importScripts(...) line to the top of your serviceworker.js file.
    • HTML File Changes (If Web Personalization Enabled): Add the generated <link> tags and the Personalization <script> tag to the top of the <head> section of your root HTML file.
    • Initialize the SDK:
      • For CDN: Paste the initialization script directly into the <head> tag.
      • For NPM: Paste the import statement and the Moengage.initialize({...}) block into your main JavaScript file.
Post-requisiteAfter integrating, verify the setup by opening your browser’s Developer Tools (Network tab). Reload the page and confirm that requests are successfully reaching MoEngage endpoints (e.g., cdn.moengage.com or sdk-0X.moengage.com).

​
Configuration Parameters

The initialization method requires specific inputs to generate the correct code. The following table details the available fields in the configuration.
SectionField NameDescription
Integration MethodHow will you install the SDK?Determines the installation method:
  • NPM / Yarn: Selects bundlers like Webpack or Rollup.
  • CDN: Selects standard HTML Script Tag installation.
  • Other Integration: Displays direct documentation links for specialized platforms including GTM (Google Tag Manager), AMP (Accelerated Mobile Pages), Shopify, Flutter, and Smart TV.
Core ConfigurationMoEngage Workspace IDIdentifies the application within the MoEngage dashboard using a unique App ID.
MoEngage Data CenterSpecifies the data center associated with the dashboard URL. Refer here for more details.
MoEngage EnvironmentSets the data reporting environment. Use 'TEST' to send data to your test environment or 'LIVE' for production data.
Log LevelControls the verbosity of SDK logs in the browser console:
  • 0: No logs shown (Recommended for LIVE).
  • 1: Critical SDK logs and errors (Default for TEST).
  • 2: All informational, debug, error, and warning logs.
MoEngage Project IDIdentifies the specific project if the Portfolio feature is enabled.
Use Latest SDK VersionTargets the most recent version of the Web SDK automatically when enabled.
SDK VersionSpecifies the SDK version you want to target. This field is not visible if Use Latest SDK Version checkbox is selected.
Application ProfileMy website is a Single Page Application (SPA)Indicates whether your website operates as a Single Page Application (SPA).
This is for a browser extensionIndicates whether your application is a browser extension.

Note: Prevents the SDK from storing cookies and disables cross-subdomain user sharing if selected.
Feature ConfigurationEnable Web Push NotificationsIncludes the module required for collecting push tokens and displaying browser notifications.
Enable On-Site MessagingEnables the module required to display on-site campaigns, such as pop-ups and interstitials, on the website.
Enable Cards Notification InboxEnables the Notification Inbox for Cards module and unlocks the UI Customization section.
Enable Web PersonalizationEnables the web personalization module.
Disable SDK at InitializationInitializes the SDK in a disabled state.

Note: Requires an explicit call to the Moengage.enableSdk() method to enable tracking if selected.
Web Push Details
(Visible when Enable Web Push Notifications is enabled)		Service Worker PathDefines the path to your service worker file from the site root. The default path is, /serviceworker.js.
Service Worker ScopeDefines which pages the service worker can be active on. The default is / (the entire site). To limit it, enter a specific path, for example, /app/.
Cards Configuration & UI Customization
(Visible when Enable Cards Notification Inbox is enabled)		CSS Selector for Inbox IconIdentifies the HTML element that opens the inbox when clicked using its unique CSS ID or Class (e.g., #bell-icon).
Floating Bell Icon (Desktop)Configures the settings for the desktop floating bell icon:
  • Icon URL: Sets the image source for the bell icon.
  • Position: Defines the Top, Right, Bottom, and Left offsets.
  • Count Background Color: Sets the background color of the unread badge.
  • Count Text Color: Sets the text color of the unread badge.
  • Icon Background Color: Sets the background color of the bell itself.
  • Font URL: Specifies a custom font file URL.
  • z-index: Sets the z-axis stack order of the bell icon.
Floating Bell Icon (Mobile)Configures the settings for the mobile floating bell icon:
  • Icon URL: Sets the image source for the bell icon.
  • Position: Defines the Top, Right, Bottom, and Left offsets.
  • Count Background Color: Sets the background color of the unread badge.
  • Count Text Color: Sets the text color of the unread badge.
  • Icon Background Color: Sets the background color of the bell itself.
  • Font URL: Specifies a custom font file URL.
  • z-index: Sets the z-axis stack order of the bell icon.
General & IconsConfigures the global styling and icons for the inbox container:
  • Background Color: Sets the background color of the inbox container.
  • Overlay Color: Sets the color of the overlay mask behind the inbox.
  • DateTime Color: Sets the text color for the date and time display on cards.
  • Unclicked Indicator Color: Sets the color of the indicator dot for unread messages.
  • Option Button Color: Sets the color of the options/menu button on cards.
  • Icon URLs: Defines custom URLs for the Pin Icon, Refresh Icon, Close (Web) Icon, and Close (Mobile) Icon.
Card DismissalControls the ability for users to dismiss cards.
  • Enable Dismiss Option: Allows users to dismiss cards when enabled.
  • Text Color: Sets the color of the dismiss text or icon.
Navigation BarConfigures the settings for the top header of the inbox.
  • Text: Defines the header title text.
  • Text Color: Sets the color of the header title text.
  • Background Color: Sets the background color of the navigation bar.
  • Font Size: Sets the font size of the header title.
  • Font URL: Specifies the URL for a custom font file for the header.
TabsConfigures the category tabs (e.g., “All”, “Unread”).
  • Active Tab Text Color: Sets the text color of the currently selected tab.
  • Active Tab Underline Color: Sets the color of the line indicating the active tab.
  • Active Tab Background Color: Sets the background color of the active tab.
  • Inactive Tab Text Color: Sets the text color of unselected tabs.
  • Background Color: Sets the background color of the tabs container.
  • Font Size: Sets the font size of the tab text.
  • Font URL: Specifies the URL for a custom font file for the tabs.
Card ContentConfigures the typography and separation style of the cards.
  • Header Font Size: Sets the font size of the card title/header.
  • Description Font Size: Sets the font size of the card body text.
  • CTA Font Size: Sets the font size of the call-to-action button or link.
  • Font URL: Specifies the URL for a custom font file for the card content.
  • Separator Color: Sets the color of the divider line between cards.
Empty StateConfigures the visual elements displayed when there are no messages.
  • Image URL: Specifies the source URL for the image displayed when the inbox is empty.
  • Text: Defines the message text displayed when the inbox is empty.
Cards Inbox z-indexz-index Value: Sets the z-axis stack order of the inbox container.

​
Common Configuration Scenarios

You can configure environment selection and log verbosity independently to suit your development and debugging needs:
Environment (env)Log Level (logLevel)Data DestinationConsole Output
'TEST'0Test DashboardClean console (no SDK logs).
'TEST'1Test DashboardCritical logs and errors (Recommended for testing).
'LIVE'0Production DashboardProduction settings. No logs shown.
'LIVE'1Production DashboardEnables SDK error logs in production for troubleshooting.

​
Option 2: Manual Integration

You can manually integrate the SDK by configuring the initialization parameters directly in your codebase. Select your platform or framework from the list below to view the specific manual integration guide: For any manual integration, ensure you complete the following configuration steps:
  1. Specify the MoEngage Data Center for Web SDK data collection.
  2. Enable Whitelisting.
This is a 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 hostData Center
dashboard-01.moengage.comdc_1
dashboard-02.moengage.comdc_2
dashboard-03.moengage.comdc_3
dashboard-04.moengage.comdc_4
dashboard-06.moengage.comdc_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.
  5. if you have Portfolio enabled for your workspace, you need to pass the project_id key and the project ID of your project as value.
<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","identifyUser","getUserIdentities"],m={onsite:["getData","registerCallback","getSelfHandledOSM"]};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,
        env: 'TEST',
        logLevel: 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
  5. If you have Portfolio enabled for your workspace, you need to pass the project_id key and the projectID of you project as value.
<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","identifyUser","getUserIdentities"],m={onsite:["getData","registerCallback","getSelfHandledOSM"]};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,
  env: 'LIVE',
  logLevel: 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}
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. 
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',
  env: 'LIVE',
  logLevel: 0
});
You can pass any configuration here. For example,
  • if you have Portfolio enabled for your workspace, you need to pass the project_id key.
  • if you want to change the integration settings for specialized projects, then pass it as shown in the following snippet:
moengage.initialize({
  app_id: 'XXXXXXXXXXXXXXXX', 
  project_id: 'your_project_id',
  env: 'LIVE',
  logLevel: 0
});
After that, you can use any method of the Moengage SDK, as shown in the snippet below: 
moengage.add_email('[email protected]')
 
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', useLatest: true});
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

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

Check that the logLevel is set to 1 (or 2 for verbose) while initializing the MoEngage SDK.

​
How to see SDK logs in Live environment?

Configure the logLevel to 1 while initializing the MoEngage SDK.

​
What is the difference between TEST & LIVE environment?

MoEngage provides a staging environment referred to as the TEST environment. The LIVE environment contains data about your actual users/customers from your production website.  MoEngage Web SDK uses the env parameter to route data correctly:
  • env: 'TEST': Routes data to your Test dashboard.
  • env: 'LIVE': Routes data to your production dashboard.
You can independently control log verbosity using the logLevel parameter regardless of the environment selected.