Enabling Web Push (For Automation Service)

Metrix creates a server-side User for each user to send push notifications (if a User does not already exist for that user). This User is created after obtaining the user’s permission to send push notifications and can be viewed in the Metrix dashboard under User Lookup.

If the authorizeUser method is not called for a user who has granted permission to receive push notifications, this user will be created as an Anonymous user on Metrix servers. Essentially, in this case, a User is created on Metrix servers for each device that grants push notification permission.

However, if you want a user who has granted push notification permission to be registered as an Identified (non-anonymous) user in Metrix, the authorizeUser method must be called for that user beforehand. Additionally, you can use related User methods to complete or update that User’s information.

You can use the following sample implementations to implement WebPush on your website.

• Netxjs sample 
• Pure html/js sample 

To enable WebPush, follow these steps:

Step 1: Adding the ServiceWorker file (only for websites with HTTPS protocol)

If your website does not have a ServiceWorker file, or if the existing file has not been used for sending web push notifications to users, download this file  and place it in the root of your project. (This means it should be in the same directory as files like index.html or index.php.)

note: This file must be accessible at the base URL of your website. For example, if your website’s domain is https://dashboard.metrix.ir , the file should be accessible at https://dashboard.metrix.ir/metrix-sw.js 

However, if your website already has a ServiceWorker file that performs tasks other than sending web push notifications, simply add the following line to that file and then register the ServiceWorker before requesting the user’s permission to send push notifications.

importScripts('https://cdn.metrix.ir/sdk/web/metrixweb-sw.js');

Also, include hasSW: true in the web push setup configuration.

Step 2: Enable Push Settings

The settings related to sending push notifications are done through the third parameter of the init method, known as config.

Web push setup configuration:

{
  push: {
    enabled: true; // default is false but if set to true you must provide publicKey.
    publicKey: YOUR_PUBLIC_KEY; // your push subscription public key.
    hasSW: false; // (OPTIONAL) default is false, if you already have a serviceWoker that does something except sending webpush set this to true.
  }
}

The publicKey will be provided by Metrix.

Step 3: Request User Permission

You can request permission to send notifications in two ways.

Method 1: Using subscribePush()

You can call the subscribePush() method in any desired section of your website (for example, in a custom popup) to request the user’s permission to receive push notifications.

subscribePush() : Promise<ConfirmPushState>

This method returns a Promise of type ConfirmPushState, which indicates the user’s action status regarding accepting or declining push notifications.

User action status regarding push notification permission

type ConfirmPushState = 'subscribed' | 'blocked' | 'closed';

Please note that calling the init method with the push notification settings (in the config parameter) must be done before calling the subscribePush method.

Method 2: Backdrop

The Backdrop can be displayed to the user in two ways to obtain permission for receiving push notifications. These two methods are:

1. Automatically on SDK initialization:

You can open the backdrop when the SDK starts by adding the following parameters to the push configuration. The opening of the backdrop can be delayed by setting the backdropDelay value, and the text displayed inside it can be customized using the backdropText value.

{
  push: {
  ...
  showBackdrop: true,
  backdropDelay: 1000,  // Delay time in ms.
  backdropText: 'SAMPLE_TEXT', // Text to show inside backdrop.
}
}

2. Manually by calling openPushConfirmBackdrop():

By calling the openPushConfirmBackdrop method, you can display the backdrop at any desired time. This method, similar to the previous approach, returns a ConfirmPushState as a Promise, indicating the user’s decision regarding push notification permission.

openPushConfirmBackdrop({
  backdropDelay: 1000, // Delay time in ms.
  backdropText: 'SAMPLE_TEXT', // Text to show inside backdrop.
}): Promise<ConfirmPushState>

Method 3: Metrix Bell

By adding showBell: true to the push settings, the Metrix bell icon will be displayed on the website. By clicking on this icon, the user initiates the process of requesting permission to receive push notifications.

{
  push: {
  ...
  showBell: true // default is false
}
}

Important Notes for Sending Push Notifications on iOS

Due to limitations in the iOS operating system, the following points must be observed when sending push notifications:

• According to this link   ، push notifications are supported on iOS starting from versionios 16.4 and on macOS from version 13 onwards.

• On iOS, only Progressive Web Apps (PWA) that have been installed via “Add to Home Screen” are permitted to send push notifications. (Even websites that have been added to the home screen but are not PWAs will not be able to send push notifications. Therefore, you must use a PWA application.)

• The permission prompt for sending push notifications must be displayed in response to a direct user interaction (such as clicking a button). As a result, calling the subscribePush method or opening theBackdrop during app load will have no effect and will be blocked by the operating system. (This restriction applies equally to Safari and Chrome browsers.)

Check the user’s push notification permission status

Using the following method, you can check the user’s browser permission status for receiving push notifications:

onPushStateResolved(): Promise<ConfirmPushState>

This method returns aPromise of type ConfirmPushState, whose states can be viewed here.