FAQ

About the unique user identifier user_str

1. During initialization, the developer must provide a unique string (user_str) to generate the user's unique identifier code (UID). This UID is used for push notification identity recognition and is independent of the user's device.
   

2. If a user subscribes on multiple browsers or devices using the same user_str, the system will identify them as the same user. The new subscription information will replace the old information, ensuring that the user receives messages on the device/browser used for the most recent subscription. This prevents the same user from receiving duplicate messages on multiple devices/browsers. The system backend stores only the latest subscription information for each UID.
   

3. Users can unsubscribe at any time, and our SDK provides the corresponding interface to implement this feature. The unsubscribe operation will unbind the UID from the subscription information, but it will not change the browser's notification permission settings.
   

4. In theory, user_str should correspond one-to-one with the user account. In some scenarios, users may be in guest mode. In this case, developers need to generate a unique user_str based on the actual situation. Our SDK does not automatically handle this step in order to avoid inaccurate statistical data caused by improper handling of user_str.
   

For users in guest mode, developers can use the following example function to generate a user_str based on the uniqueness of the user's browser. However, please note that this approach may cause a new user_str to be generated if the user changes browsers, changes devices, or clears the cache.
Example function

function randomUid() { const keyStr = 'mtWebPushRandomUid'; let uid = window.localStorage.getItem(keyStr); if (!uid) { uid = new Date().getTime().toString(36) + Math.floor(Math.random() * 10000000).toString(36); window.localStorage.setItem(keyStr, uid); } return uid; } var user_str = randomUid();

              
              function randomUid() {
  const keyStr = 'mtWebPushRandomUid';
  let uid = window.localStorage.getItem(keyStr);
  if (!uid) {
    uid = new Date().getTime().toString(36) + Math.floor(Math.random() * 10000000).toString(36);
    window.localStorage.setItem(keyStr, uid);
  }
  return uid;
}
var user_str = randomUid();

            

This code block in the floating window

Which platforms support Web Push?

Browser support by operating system

Note 1: Microsoft Edge (updated in 2019), Opera, Samsung Internet, Yandex, and UC Browser are all Chromium-based browsers and will be marked as Chrome in EngageLab.
Note 2: Internet Explorer no longer receives feature updates. Microsoft has shifted browser development to the Edge platform.
Note 3: Incognito mode, private browsing mode, and guest browser mode do not support web push notifications.

Support by browser version

Web Push notification issues related to the Safari browser

Web Push notifications on Safari are supported on macOS (11.1+) and iOS/iPadOS 16.4+.

Which features does Safari push support?

How can users on iOS and iPadOS receive Safari web push notifications?

1. How should developers configure settings so users can receive web notifications on iOS/iPadOS 16.4+?

Web Push notifications can be used on iOS/iPadOS 16.4+. However, the website must have a proper manifest file and the correct properties configured in order for notifications to work properly. Add the following code to the HTML of the corresponding integration page: <link rel="manifest" href="manifest.json" />

Include the manifest file:

              
              {
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "display": "standalone",
  "start_url": "/webpush/index.html",
  "name": "Engagelab WebPush Example",
  "short_name": "Engagelab",
  "icons": [
    {
      "src": "/icon-large-cb438cac.png",
      "type": "image/png",
      "sizes": "1024x1024"
    }
  ]
}

            

2. In order for users to subscribe to and receive mobile Safari Web Push notifications, they must add the web app to the Home Screen

Sending mobile Safari Web Push notifications (for iOS and iPadOS 16.4+) requires notification recipients to do the following:

• Visit your website in the Safari browser on a mobile Apple device running 16.4+.
• Tap the Share button in Safari on the mobile device.
• Tap the "Add to Home Screen" option.
• Save the app on the device.
• Open the app from the Home Screen.
• Subscribe to notifications (before the native permission prompt appears, they must tap the subscribe button). These steps are required in order to receive mobile Web Push notifications.

Because this interaction flow is relatively complex for end users, you need to help them understand the benefits of subscribing to notifications.

3. Add a banner notification on your website to guide users to "Add to Home Screen"

You can add a banner to your website to inform end users about the value of mobile Web Push notifications and guide them on how to subscribe.
We recommend adding a banner to your website that appears on mobile Apple devices and guides visitors to tap the Share button and the "Add to Home Screen" option.
There is also a popular open-source project that can help you provide these instructions to users:
Bottom banner example GitHub link: https://github.com/rajatsehgal/add-to-home-screen

Can users receive notifications if the browser is closed?

• When using the EngageLab channel, notifications can only be received when the website is open.
• When using the system channel, notifications can be received even when the browser is closed, although behavior differs across platforms. See the table below for details:

On Windows, if all windows are closed but the browser is still running in the background, system notifications can still be received. If the browser process has been closed, system notifications will not be received.
On macOS, even if all windows are closed, most browser processes continue running in the background, so system notifications can still be received. If the browser process is force-quit, system notifications will not be received. Safari does not need to be running to receive notifications, because they are delivered directly to the operating system. Users need to register Safari notifications first, and afterward they can still receive notifications even if Safari is completely closed.

Issues related to notification permission prompts

After a user closes the web push prompt, when will the prompt appear again?

If a user clicks "Block" (Chrome), "Don't Allow" (Safari), or "Never Allow" (Firefox) on the native permission prompt, the website will not be able to prompt them again unless the user goes through multiple steps in the browser settings to subscribe or reset permissions. This is why using the EngageLab prompt (Go to settings) is recommended.

Native permission prompt

Web Push subscriptions require the native browser permission prompt, and the native permission prompt cannot be customized. It uses the language set in the user's browser settings. Only HTTPS websites can display the native browser prompt.

Chrome: You have 3 chances to get users to subscribe. After the user clicks the "X" on the native permission prompt for the third time, the user will not receive the prompt again for one week. For more information about this Chrome feature, see here.
Firefox: Starting from Firefox 70, after a user clicks the close button, they need to click the small notification icon in the browser to receive the prompt again. In addition, for Firefox 72+, the native browser prompt has been blocked from displaying. For details, see here.
Safari: Similar to Firefox, Safari added a quieter UI for users who usually reject permissions and automatically prompts websites that have been denied push permissions, Safari 12.1+

EngageLab soft prompt

Because the native popup gives only one chance, if the user rejects it, the website will not be able to request authorization from the user again. Therefore, EngageLab recommends using a "soft prompt" to obtain user authorization:
If the user clicks "Allow" or "Cancel" on the EngageLab prompt (Go to settings) and still has not subscribed through the native prompt popup, the EngageLab prompt can appear again.

• After the user clicks "Allow" on the EngageLab prompt, the native popup will be triggered. However, if the user clicks "Cancel" on the native prompt at this time, the next time the user enters the website, the EngageLab prompt will still appear and ask whether they want to allow notifications from the website.
  
• After the user clicks "Allow" on the EngageLab prompt, the native popup will be triggered. If the user clicks "Allow" on the native prompt at this time, the user authorizes the website for web notifications; if the user clicks "Deny" on the native prompt at this time, the website will no longer be able to obtain authorization from the user again.
  
• If the user clicks "Cancel" on the EngageLab prompt, it can be determined that the user does not currently wish to receive notifications from the website. Since asking at this time is likely to be rejected, we will not trigger the native popup, and the next time the user visits, we can ask again through the EngageLab prompt whether they want to receive notifications.

Troubleshooting when notifications are not received

1. Check whether notification permissions are enabled for the webpage

2. Check whether notification permissions are enabled for the browser application
Windows notification settings:

• Turn off Focus Assist. For details, refer to the official Microsoft documentation.
• Check Settings > Notifications & actions > Get notifications from apps and other senders. Make sure your site and browser are also enabled. For more details, refer to the official Microsoft documentation.

macOS notification settings:

• In System Preferences > Notifications > Chrome or the selected browser, make sure Allow Notifications is turned on.
• In System Preferences > Notifications > Focus > Do Not Disturb and Sleep, make sure this mode is not enabled or that you are within an allowed notification time period.
• macOS also has a temporary Do Not Disturb notification setting in the upper-right menu; scroll upward to view it.

3. Browser vendor channels may be unstable, so switch to prioritizing delivery through the EngageLab channel

              
              {
  "from": "web_push",
  "to": {
    "registration_id": [
      "xxx"
    ]
  },
  "body": {
    "platform": "web",
    "notification": {
      "web": {
        "title": "web_push",
        "alert": "Hi,MTPush !",
        "url": "http://www.google.com",
        "extras": {
          "web-key1": "web-value1"
        }
      }
    },
    "options": {
      "time_to_live": 30,
      "third_party_channel": {
        "w3push": {
          "distribution": "mtpush"
        }
      }
    },
    "request_id": "12345678",
    "custom_args": "business info"
  }
}

            

Safari browser cannot pop up notifications?

Step 1: Check Safari browser permissions and make sure the allow switch is turned on. A normal state is shown below:

Step 2: Click to check the push service status and browser notification permissions. A normal state is shown below:

Step 3: In Safari, click Preferences.

Click Websites > Notifications, and check whether the site is allowed in Notification Center. A normal state is shown below:

Special note:

1. Clicking Stop Push will prevent receipt of JPush messages, and the page needs to be refreshed.
2. If multiple HTML pages are configured under one domain, do not remove the website permission from Notification Center. After removal, all HTML pages will stop receiving notifications (the user will need to find the main page and obtain website notification permission again).

If the same user uses multiple browsers at the same time and one message is sent to that user, how will it be displayed on the user's device?

If the selected delivery strategy is to prioritize the system channel, then this message will only be delivered through the browser vendor channel used most recently by the user. If delivery is selected only through the JPush channel, then multiple messages will be delivered.

If the user clears the browser cache and cookies, can they still receive Web Push from this website?

When the user is online, the JPush channel can still receive pushes.
For browser vendor channels, when users clear browser cookies and cache, they will unsubscribe from notifications. This is because subscriber user data is stored in the browser's IndexedDB storage. Removing this data causes the browser to "forget" the subscriber. However, clearing this data does not remove the user's permission that has already been granted to receive notifications in that browser. At this point, SDK initialization is required so that the user can be automatically re-subscribed when they return to the website.
However, if the user changes the browser notification permission to "Ask" or "Block," they will not be automatically re-subscribed.
If the user clears notifications from the browser's notification settings, they also will not be automatically re-subscribed.

How to clear notifications in each browser:

• Chrome: chrome://settings/content/notifications
  

• Firefox: about:preferences#privacy > Permissions > Notifications
  

• Safari: Preferences > Websites > Notifications > Remove
  

When the user re-subscribes, they will get a new Registration ID record. You can use window.MTpushInterface.getRegistrationID() to get the RID.

If multiple messages are sent to the same user at the same time, will all messages be displayed?

The message display mechanism varies by push channel:
EngageLab channel: No override mechanism. If multiple messages are sent to the same user at the same time, multiple messages will be displayed to the user simultaneously. Notification Center will retain multiple messages; except for the most recent message, the others will be collapsed.
Safari: No override mechanism. If multiple messages are sent to the same user at the same time, multiple messages will be displayed to the user simultaneously. Notification Center will retain multiple messages; except for the most recent message, the others will be collapsed.
Chrome: Has an override mechanism. If multiple messages are sent to the same user at the same time, each notification will be replaced by the updated notification, and only the last sent message will be displayed.
Edge: Has an override mechanism. If multiple messages are sent to the same user at the same time, each notification will be replaced by the updated notification, and only the last sent message will be displayed.
Firefox: Has an override mechanism. If multiple messages are sent to the same user at the same time, each notification will be replaced by the updated notification, and only the last sent message will be displayed.

Does EngageLab WebPush support changing domains?

Browsers have already implemented Web Push in a way that binds subscribers to a specific origin (domain name/website URL).
For security reasons and due to the browser's same-origin policy, browsers do not allow subscribers to be moved to another origin. This is not an EngageLab limitation. If any provider claims they can move subscribers from one website to another, be sure to confirm that what they are subscribing to is actually your website.
If you have changed your website, the best solution is to set up a new WebPush app for the new website and have your users subscribe to the website under this new app. You cannot import subscribers from one origin to another.
You can continue sending push notifications to subscribers of the old website (old WebPush app), but your users need to re-subscribe to the new website in order to receive pushes from the new domain. The recommended migration steps are as follows:

• Set up a new WebPush app for the new site domain.
  
• Continue sending pushes from the old WebPush app using the old site domain. In the notification's "Launch URL," use the new site domain.
  
• After 2 weeks to 2 months (depending on how many notifications you send daily and how many subscribers you gain on the new website), you can stop using the old WebPush app and use only the new WebPush app.
  
• If you send the same message from both the old WebPush app and the new WebPush app, subscribers under both will receive duplicate messages. This is why we recommend following this timeline.
  
• You can send several messages such as "We have moved. Click here to visit our new website and re-subscribe to stay updated." This will help remind users that they may no longer receive pushes from your website if they do not return and re-subscribe. It is recommended to send this kind of notification at the start of the migration and with the last message sent from the app.
  
• Unfortunately, every website and user group is different. Please be prepared to lose subscribers in the short term.
  

When carrying out the migration steps above, be sure to pay attention to the user experience to avoid inconvenience to users.

Does EngageLab WebPush support PWA push?

1. What is PWA?

PWA push refers to the process of using Web Push technology in Progressive Web Apps (PWAs) to send notifications to users. A PWA is an application built using web technologies that provides functionality and a user experience similar to a native application, while also being accessible through a browser without installation.
PWA push is implemented through the Web Push technology provided by the browser. Web Push technology enables web applications to send push notifications like native applications, even when the application is not active or is completely closed.
Unlike traditional applications, PWAs do not need to be downloaded and installed from an app store and can be accessed directly through a URL in the browser. At the same time, PWA push can provide timely message alerts to users, enhancing user experience and engagement.
In short, PWA push is a method of using Web Push technology to send notifications to users of Progressive Web Apps, improving user engagement and interaction while providing web applications with a user experience closer to that of native applications.

2. Does EngageLab WebPush support PWA push?

The EngageLab WebPush service supports PWA push. You need to use the Web SDK provided by EngageLab WebPush to integrate Web Push functionality into your PWA application, and follow the example code in the documentation to register a Service Worker and initialize Web Push functionality. Once the integration is complete, you can use the EngageLab WebPush API to send push notifications to users of your PWA application.

Note: There are two necessary conditions for the Web SDK to support PWA:

1. The application runs in a browser, and the browser supports W3C notifications.
2. There is a specific domain name, and it uses the HTTPS protocol.

3. Will the PWA service worker conflict with the EngageLab WebPush service worker?

The service worker of a PWA (Progressive Web App) and the service worker of EngageLab WebPush may conflict, because both run in the browser background, and for the same origin, usually only one service worker can be active at a time.

Service workers are scripts installed by websites in the browser and can support offline experiences, push messaging, background sync, and more. Because service workers control pages within their scope, multiple service workers cannot control pages simultaneously under the same scope.

If you try to register multiple service workers under the same application/domain, the one registered later may replace the previous one, or conflicts may occur when the scopes of the two service workers overlap. This conflict may lead to unexpected behavior, such as push messaging functioning properly through only one channel.

To avoid this conflict, you can:

1. Make sure you use only one service worker in your application. If the Web Push functionality provided by EngageLab and your PWA functionality can be implemented through the same service worker, it is best to combine them into one service worker script.

2. If you need to use two separate service workers, you should ensure that their scopes do not overlap. This can be achieved by specifying different scope paths when registering the service workers.

Before implementation, it is recommended to read the relevant documentation carefully and conduct sufficient testing in both development and production environments to ensure that the service workers can coexist without interfering with each other.

4. Differences in PWA app notification permission popup behavior on iOS and Android devices

• iOS system restrictions (Safari/WebKit policy):
  · For privacy reasons, iOS requires a user gesture (such as a click) before a permission popup can be triggered.
  · This is a mandatory WebKit policy and applies to all PWAs and web applications.
  · After a PWA is installed for the first time, user interaction is still required before requesting permission.

• Android system characteristics:
  · Chrome/WebView allows permissions to be requested automatically when the page loads.
  · Follows a more lenient permission request model.
  · Some Android versions even support progressive permission prompts.

Why can the registration ID be the same across different browsers?

Answer: For the same integrated domain name configured for one application and the same user userStr, the same RID will be generated, regardless of whether it is the same browser.

• To check whether it is the same user, use the following method: view the HTML source code and find the initialization function.

              
              // Please register event listeners before initialization
// Callback when the JPush channel is disconnected
MTpushInterface.mtPush.onDisconnect(function () {
  console.log("onDisconnect");
});

// Receive push messages (web push, browser vendor channel)
MTpushInterface.onMsgReceive((msgData) => {
  // msgData data structure {data:{xxx},type:0} type:0 is the JPush channel, 1 is the system channel
  console.log("Received push message:", msgData);
});

// Push initialization
MTpushInterface.init({
  appkey: "", // Required. See above for how to get application information
  user_str: visitorId, // Required. User identifier used to identify the user
  fail(err) {
    console.log("Failed to create online push", err);
  },
  success(data) {
    console.log("Online push created successfully", data);
  },
  webPushcallback(code, tip) {
    console.log("Status code and prompt received by the user", code, tip);
  },
  swUrl: '', // Default "/sw.min." + sdkEnv.version + ".js". This configuration item is the service worker file address. The domain name must be the current domain name, and the path determines the service worker scope.
  canGetInfo(data) {
    // At this point, you can get some notification configuration data, and after this callback function you can get the RegId
    console.log(data); // Related configuration information
    console.log("Get RegId", MTpushInterface.getRegistrationID());
  },
  custom: (fuc) => {
    // When using a custom prompt configuration, you need to manually call fuc() to request notification permission.
    // The function to request notification permission can only be obtained through custom.
    // Calling fuc() will request notification permission
  },
});

            

If you encounter any issues during use that are not covered in this document, feel free to contact us at any time. We will provide you with professional support and answers.