Implement offline push notification

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of sending offline push notifications. That is, in one-on-one chat or group chat, if your app is frozen, killed by the system or a user in the backend, and get disconnected with the ZEGOCLOUD service backend due to timeout, with the offline push notification feature, the ZEGOCLOUD backend will send offline push notifications to the target users.

You can integrate the ZPNs SDK and use it together with the ZIM SDK to implement the offline push notification feature.

Warning

For Web apps to use this feature:

only Chrome and Edge browsers are supported because its implementation depends on the Google FCM.
The ZPNs SDK needs to be used together with a ZIM SDK 2.3.0 or later.

Solution

The solution we provide is as follows:

The receiver (the client user that receives the offline push notifications) enables Google's push notification channel, and sends a request to get the Token from the Google Server.
Google Server returns the Token to the receiver.
The receiver generates a PushID, and sends it to the ZIM Server for binding the client user and PushID.

You need to use the ZPNs SDK together with the ZIM SDK, the SDK will automatically bind the client user to PushID, and you don't need to do other operations; Note: Before switching the userID on the same device, remember to call the logout method to remove the PushID that userID is binding.
The sender starts sending messages, and the messages are stored in the ZIM Server.
The ZIM Server checks whether the receiver is online.
If the receiver is offline, then the messages will be transferred to the ZPNs Server.
The ZPNs Server sends offline push notifications to the Google Server.
Google Server pushes the offline push notifications to the receiver. The receiver receives the offline messages when gets back online.

Implementation steps

Integrate Google push notification channel

Integrate Google's push notification channel by referring to the Integrate FCM.

Integrate the ZPNs SDK

Download the latest version of the ZPNs SDK.
Extract the downloaded SDK package to your project folder, such as the zego-zpns-web folder.
Import the SDK.
1. Modify the project's index.html file and add the following code:
```
<script src="./zego-zpns-web/index.js"></script>
```
```
<script src="./zego-zpns-web/index.js"></script>
```
1. Copy the zego-zpns-web/firebase-messaging-sw.js file to your project's root directory.

Set up the offline push notification feature using the ZPNs SDK

Set up the offline push notification feature.

const appID = 0; // Your Application ID of ZEGO ZIM
ZIM.create({ appID: appID });
const zim = ZIM.getInstance();

const config = {
    // From firebaseConfig
    apiKey: '',
    authDomain: '',
    projectId: '',
    storageBucket: '',
    messagingSenderId: '',
    appId: '',
    measurementId: '',

    // From Web Push certificates
    vapidKey: '',
}
ZPNs.getInstance().register(config, zim);

const appID = 0; // Your Application ID of ZEGO ZIM
ZIM.create({ appID: appID });
const zim = ZIM.getInstance();

const config = {
    // From firebaseConfig
    apiKey: '',
    authDomain: '',
    projectId: '',
    storageBucket: '',
    messagingSenderId: '',
    appId: '',
    measurementId: '',

    // From Web Push certificates
    vapidKey: '',
}
ZPNs.getInstance().register(config, zim);

After finishing using this feature, call the unregister method to cancel this feature. Users can't receive any notifications after it is canceled successfully.
```
ZPNs.getInstance().unregister();
```
```
ZPNs.getInstance().unregister();
```

Implement the offline push notification feature with the ZIM SDK

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of sending offline push notifications for one-on-one or group chats, and call invitations .

Warning

Before implementing offline push, you should:

refer to Send and receive messages to send one-on-one/group chat messages.
refer to Call invitation to send and receive call invitations.

Send one-on-one messages with offline push notification

Set the offline push notification title, content, and other properties in the ZIMPushConfig object.

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

const sendConfig: ZIMMessageSendConfig = {
    priority: 2,
    pushConfig: pushConfig
};

const sendConfig: ZIMMessageSendConfig = {
    priority: 2,
    pushConfig: pushConfig
};

The message sender calls the sendMessage method with the sendConfig to send one-to-one messages.

const toUserID = '';
const messageTextObj: ZIMTextMessage = { type: 1, message: 'text' };
zim.sendMessage(messageTextObj, toUserID, 0, sendConfig)
.then(function ({ message }) {
    // Operation succeeded
})
.catch(function (err) {
    // Operation failed
});

const toUserID = '';
const messageTextObj: ZIMTextMessage = { type: 1, message: 'text' };
zim.sendMessage(messageTextObj, toUserID, 0, sendConfig)
.then(function ({ message }) {
    // Operation succeeded
})
.catch(function (err) {
    // Operation failed
});

The offline receiver will receive the offline messages when gets back online.

Send group messages with offline push notification

Set the offline push notification title, content, and other properties in the ZIMPushConfig object.

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

const sendConfig: ZIMMessageSendConfig = {
    priority: 2,
    pushConfig: pushConfig
};

const sendConfig: ZIMMessageSendConfig = {
    priority: 2,
    pushConfig: pushConfig
};

The message sender calls the sendMessage method with the sendConfig to send group messages.

const toGroupID = '';
const messageTextObj: ZIMTextMessage = { type: 1, message: 'text' };
zim.sendMessage(messageTextObj, toGroupID, 2, sendConfig)
.then(function ({ message }) {
    // operation succeeded
})
.catch(function (err) {
    // operation failed
});

const toGroupID = '';
const messageTextObj: ZIMTextMessage = { type: 1, message: 'text' };
zim.sendMessage(messageTextObj, toGroupID, 2, sendConfig)
.then(function ({ message }) {
    // operation succeeded
})
.catch(function (err) {
    // operation failed
});

The group members who are offline can receive offline messages when getting back online in the group.

Send call invitations with offline push notification

Set the offline push notification title, content, and other properties in the ZIMPushConfig object.

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

const pushConfig: ZIMPushConfig = {
    title = "offline push notification title";
    content = "offline push notification content";
    // extendedData = "Customizable field, optional."; //  applicable when ZIM version < 2.5.0
    // payload = "Customizable field, optional.";  // applicable when ZIM version >= 2.5.0
    resourcesID = "resource ID, optional";
}

Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMCallInviteConfig object.

const callInviteConfig: ZIMCallInviteConfig = {
    mode: 0,
    timeout: 90,
    extendedData: '',
    pushConfig: pushConfig
}

const callInviteConfig: ZIMCallInviteConfig = {
    mode: 0,
    timeout: 90,
    extendedData: '',
    pushConfig: pushConfig
}

The message sender calls the callInvite method with the callInviteConfig to send group messages.

const invitees = ['xxxx'];  // Invitee ID list
zim.callInvite(invitees, callInviteConfig)
    .then(function({ callID, timeout, errorInvitees }){
        // Operation succeeded
        // The callID here is the ID generated internally by the SDK after the user initiates a call, which is used to uniquely identify a call invitation. Afterwards, when the initiator cancels the call or the invitee accepts/rejects the call, this callID will be used.
    })
    .catch(function(err){
        // Operation failed
    })

const invitees = ['xxxx'];  // Invitee ID list
zim.callInvite(invitees, callInviteConfig)
    .then(function({ callID, timeout, errorInvitees }){
        // Operation succeeded
        // The callID here is the ID generated internally by the SDK after the user initiates a call, which is used to uniquely identify a call invitation. Afterwards, when the initiator cancels the call or the invitee accepts/rejects the call, this callID will be used.
    })
    .catch(function(err){
        // Operation failed
    })

The invitees who are offline can receive an offline push notification. Once they come online, if the call invitation is still ongoing, they will receive the callback callInvitationReceived.

Unregister Offline Push

If you want a device to stop receiving offline push notifications, you can unregister by calling the unRegisterPush interface. After unregistering, popup push notifications and silent push notifications will no longer take effect.

ZPNs.getInstance().unregisterPush();

ZPNs.getInstance().unregisterPush();

More Features

Get Additional Information

The offline push sender sends additional information to the recipient through the payload (extendedData for versions before 2.5.0) of the ZIMPushConfig. When the recipient uses the ZPNs SDK, the user can retrieve this information from the payload field in the extras of the service provider channel.

Download version 2.5.0 or above of the ZPNs SDK from SDK downloads and copy the firebase-messaging-sw.js file to the root directory of your project.
Open the firebase-messaging-sw.js file and rewrite the following methods as needed, then save the file.

self.onNotificationArrived = function onNotificationArrived(message) {
    // Get the payload field
    console.log(message.extra ? message.extra.payload : message.extra);
}
self.onNotificationClicked = function onNotificationClicked(message) {
    // Get the payload field
    console.log(message.extra ? message.extra.payload : message.extra);
}

self.onNotificationArrived = function onNotificationArrived(message) {
    // Get the payload field
    console.log(message.extra ? message.extra.payload : message.extra);
}
self.onNotificationClicked = function onNotificationClicked(message) {
    // Get the payload field
    console.log(message.extra ? message.extra.payload : message.extra);
}