Configure and Integrate Web Push

Update the MoEngage web SDK initialization script on your website to configure and integrate Web Push.

For more information, refer to Web SDK Integration.

Ensure that you configure the web push notifications settings since enabling the Web Push module is a mandatory pre-requisite.

You can configure the web SDK integration by loading the serviceworker.js file.

Data Center

The following table has details of the different data centers in MoEngage. This information is required for integration.

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

ServiceWorker.js file restrictions

  • The serviceworker.js file is available in the root directory; if not, Web Push will not work on all the pages.
  • Ensure that the service worker file is exactly named serviceworker.js. Otherwise, refer to rename serviceworker section.

Get the serviceworker.js file.

info

Note

To integrate Web Push with the Web SDK, ensure that the serviceworker.js file is hosted in the root directory of your web server.

Choose any one of the following options for the serviceworker.js file:

Download the MoEngage Serviceworker.js

Right-click and download to save the file.

Dashboard host Service worker file
dashboard-01.moengage.com serviceworker.js
dashboard-02.moengage.com serviceworker.js
dashboard-03.moengage.com serviceworker.js
dashboard-04.moengage.com serviceworker.js

Use an existing Serviceworker.js

If you have an existing serviceworker.js file, then update the serviceworker.js file by adding the following code to the top of your file.

JavaScript
// Add this line to the top of the file
// replace the {DC} with the proper data center from the above table. eg, dc_1, dc_2 etc
importScripts("https://cdn.moengage.com/release/{DC}/serviceworker_cdn.min.latest.js");
...

Rename the Service worker custom filename.

If you wish to change the serviceworker.js file name depending on the browser or environment, use the following initialization block:

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{AppID}"; // Replace "AppID" 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,
  swPath: "/your-custom-sw.js"
});
</script>
warning

Warning

Push Notification or serviceworker.js will not work if you do not ensure the additional attribute swPath: "/your-custom-sw.js is included in the serviceworker.js file. The path informs the SDK about the custom serviceworker filename you want to use. 

For more information, refer to Sample Code.

Service worker Scope

The scope of the service worker determines which files the service worker controls; in other words, from which path the service worker will intercept requests. The default scope is the location of the service worker file and extends to all directories below. So if service-worker.js is located in the root directory, the service worker will control requests from all files in this domain.

You can also set an arbitrary scope by passing in an additional parameter swScope when initializing.

For example:

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{AppID}"; // Replace "AppID" 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,
  swPath: "/a/your-custom-sw.js"
});
</script>

In this case, we are setting the scope of the service worker to /a/, which means the service worker will control requests from pages like /a/, /a/lower/ and /a/lower/lower, but not from pages like /a or /, which are higher.

Bypassing serviceworker scope

If you are not able to place the serviceworker.js file at the root of your app but still want it to be available throughout the app, then you have to pass `swScope` as in the following snippet:

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{AppID}"; // Replace "AppID" 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,
  swPath: "/a/your-custom-sw.js",
  swScope: '/a/'
});
</script>

Disable WebPush

By default, the Web Push module is enabled for all the users. If you do not want to use it, then you have to disable it explicitly.

Pass disable_web_push: true to the initialization config to disable the Web Push Notification module:

JavaScript
<script type="text/javascript">
var moeDataCenter = "{DC}"; // Replace "DC" with the actual Data center value from the above table
var moeAppID = "{AppID}"; // Replace "AppID" 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,
  disable_web_push: true,
});
</script>

 

Troubleshooting

Registration Error

If you get the error Error in Subscription: DOMException: Registration failed - storage error, then you are unregistering the serviceworker.js somewhere from your code. Search for unregister() in your codebase and remove it.

Push Notification or serviceworker.js not working

Follow these steps:

  1. Ensure to add the MoEngage serviceworker code to your serviceworker.js file.
  2. Ensure to add swPath with the path of the serviceworker.js file while initializing the MoEngage script.

I am not getting Chrome Push Notification on my Mac.

If your Chrome is in full screen on Mac OS, you cannot see any Chrome Push notifications. This is a known issue with Chrome full screen on Mac OS, and we will update you when it is fixed by Chrome/Apple.

My Users are not able to see Web Push Notifications.

To correctly receive and view Web Push Notifications, the notifications need to be enabled for the browser through the OS settings. It may have been blocked at the OS level. Make sure it is enabled. In this case, the browser will try to show the notification; hence, the events and impressions will be tracked. But the OS will block it. Refer to this image:

image-20221212-082616.png

How do I test Web Push Notifications?

Many times before creating a Web Push campaign, you may wish to see how the push message appears. To do the testing, use the Device Push Token in Campaign Creation -> Scheduling & Goals tab -> Test Campaign section. To find your Device Push Token for your website on the Chrome browser, follow these steps:

  1. Go to your website where you have given the push permission.
  2. Right Click --> Inspect
  3. Click on the Application tab.
  4. On the left pane under Storage, click on Local Storage
  5. Under Local Storage, click on your HTTPS Website URL or HTTPS Subdomain (https://yourwebsite.moengage.com) for your HTTP Website
  6. You will find a Key MOE_DATA. Look for the PUSH_TOKEN field. Copy the corresponding Value and paste it under Test Campaign Section -> Device Push Token.

Or you can install the MoEngage Chrome Extension to see it easily. For more information, refer to MoEngage Chrome Extension.

I am not able to render the web push notification badge icon; it just shows as an empty white square.

The Android documentation states, "Update or remove assets that involve color. The system ignores all non-alpha channels in action icons and the main notification icon. You should assume that these icons will be alpha-only. The system draws notification icons in white and action icons in dark gray."
To convert your icon to an Android-compatible format-

  1. Open your notification icon in any image editor
  2. Convert all parts of the image that you don't want to show to transparent pixels. All colors and non-transparent pixels are displayed in white. Therefore, only Alpha channel (black & white) images are supported, and RGB images are not supported
  3. The resolution of the image should be 72x72 or higher
  4. Save the image in one of the following filetypes only- png, gif, webp, ico, cur, bmp

webpush_badge_icon_info.svg

On clicking Push Notifications on Firefox Android, it did not redirect me to the Firefox browser.

This is an anomaly observed in Firefox for Android. If the notification was supposed to redirect you to http://example.com

Case 1:

Firefox is open when the notification is clicked; you are redirected normally.

Case 2:

Firefox is in the background when the notification is clicked (You're on the home screen or on some other application):

Nothing seems to happen when you click the notification. But you are actually redirected in the background. So when you open Firefox next, you'll be on http://example.com.

We have raised this issue with Firefox support and are waiting to hear back from them.

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

 

Previous

Next

Was this article helpful?
1 out of 1 found this helpful

How can we improve this article?