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.

An Introduction

ZIM's offline push solution is as follows:

1. First, the receiver of the message (that is, the user who receives the offline message) opens the push channel of each manufacturer, sends a request to the push server of each manufacturer, and obtains the Token.
2. The push server of each manufacturer returns the Token to the recipient.
3. The receiver generates a PushID and sends a request to the ZIM server to bind the relationship between the user and the PushID.

If the developer uses the ZPNs SDK together with the ZIM SDK, the relationship between the user and the PushID will be automatically bound within the SDK without special handling; if the ZPNs SDK is used alone, it is necessary to connect to the ZPNs server and implement the binding logic. Please note that before switching the userID on the same device, please call the zim.logout interface, which will clear the PushID bound to the userID.

4. The sender starts to send the message, and the message is stored in the ZIM server.
5. The ZIM server will confirm whether the recipient's client is online.
6. If the recipient's client is not online, the ZIM server will forward the message to the ZPNs server.
7. The ZPNs server forwards the offline message to the push server of each manufacturer.
8. The servers of each manufacturer push the message to the recipient through the "offline push" method; the recipient can receive the offline message after logging in (at least once).

Prerequisites

Before implementing the "offline push" feature, please make sure:

Your development environment meets the following requirements:

• React Native 0.60.0 or above.

• Android

• Android Studio 2.1 or above.

• Android SDK 25, Android SDK Build-Tools 25.0.2, Android SDK Platform-Tools 25.xx or above.

• Android 9.0 or above Android device or emulator (real device recommended).

• iOS

• Xcode 7.0 or above.

• iOS 9.0 or above and an iOS device.

• The iOS device is connected to the Internet.

• A project is created in the ZEGOCLOUD console, and the application ID and the application signature for connecting to ZIM SDK are obtained. The ZIM service is activated in the ZEGOCLOUD console. For more information, see Authentication. If the ZIM service cannot be activated, contact ZEGOCLOUD technical support for help.

• Your project is integrated with ZIM SDK. For more information, see the "Integrate the SDK" section of the Send and receive messages topic.

Common Usage

1 Access the offline push channel of third-party manufacturers

Please refer to the following push integration guide to integrate the offline push SDKs of third-party manufacturers that need to be used, and access the offline push channels of each manufacturer.

Currently supports pushes from Apple, Xiaomi, Huawei, OPPO, vivo, and Google.

2 Integrate ZPNs SDK

2.1 Import ZPNs SDK

Developers can use npm to obtain the SDK.

1. Enter the root directory of your project and execute the following command to install dependencies.

   The npm download package supports the TypeScript Language(recommended).

   npm yarn

   npm i zego-zpns-react-native

   yarn add zego-zpns-react-native

2. Import the SDK.

   // import ZPNs from 'zego-zpns-react-native';  // When the SDK version is less than 2.3.0, you can export the `zego-zpns-react-native` SDK using the default method. 
   import { ZPNs } from 'zego-zpns-react-native'; // However, all versions of the SDK support exporting the `zego-zpns-react-native` SDK using a named method.

2.2 Setting Permissions

Developers can set the permissions required by the application according to the actual application needs.

• iOS：

  Call the applyNotificationPermission method to apply for notification permission from the user. This interface takes effect only when it is called for the first time. Developers are requested to pay attention to the timing of the API call.

  ZPNs.getInstance().applyNotificationPermission();

• Android：

  Enter the "app/src/main" directory, open the "AndroidManifest.xml" file, and add permissions.

  <!-- The required permissions by ZPNs SDK  -->
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.READ_PHONE-_STATE" />
  <uses-permission android:name="android.permission.GET_TASKS" />

3 Use the ZPNs SDK to register the offline push function

1. Use ZPNsEventHandler to listen for event callbacks.

The ZPNsEventHandler class contains functions for various event callbacks in ZPNs. Developers can pass in Functions to receive event callbacks in ZPNs, and handle SDK exceptions and message notification callbacks.

• throughMessageReceived : Callback for vendor throughMessageReceived. The transparent transmission messages returned by each manufacturer will trigger this interface, and a notification will be thrown on this interface.

• notificationClicked: Notification clicked callback. Triggered when the user clicks on the notification, uniformly thrown in this interface.

• notificationArrived: Notification display callback, which can be received when the App is active in the foreground.

• registered: Register the result callback of "offline push". The result of registering "offline push" will be thrown uniformly in this interface, and the PushID can be obtained through this callback.

ZPNs.getInstance().on('registered', function(message) {
    console.log('[ZPNs] registered. pushID: ' + message.pushID + ", error: " + message.errorCode)
});

2. Configure the Android third-party push channel.

According to the Prerequisites integrated third-party vendor offline push SDK, modify the corresponding boolean value, enable the push function of each vendor, and then call the setPushConfig interface to configure the third-party push channel.

ZPNs.setPushConfig({"enableFCMPush": true, "enableHWPush": true, "enableMiPush": true, "enableOppoPush": true, "enableVivoPush": true});

3. Call enableDebug to set whether the compilation environment of the current project is Debug, and the default is false. This operation is to notify ZPNs SDK whether it is a Debug environment, and the PushID generation rules are affected by this, please set it correctly before calling the registerPush interface.

ZPNs.enableDebug(true);

4. Call the registerPush interface to register offline push.

ZPNs.getInstance().registerPush();

After registering the offline push function, you can get the pushID of the offline push through the registered callback in the ZPNsEventHandler class, and push the offline message to the specified device.

4 Use ZIM SDK to realize offline push function

ZIM supports the function of offline push messages when sending single chat messages and group messages.

4.1 Use the offline push function when sending single chat messages

1. First, the developer needs to set the offline push title, content, and other custom attributes through the ZIMPushConfig object.

   var pushConfig = {
       title = "Offline push content";
       content = "Custom transparent transmission field, not required"; // Use this field when ZIM version < 2.5.0
       // extendedData = "Custom transparent transmission field, not required"; // Use this field when ZIM version >= 2.5.0
       // payload = 'Text message content' };
   }

2. Then through the pushConfig parameter of the ZIMMessageSendConfig object, configure the related configuration of offline messages, etc.

   var sendConfig = {
       priority: 2,
       pushConfig: pushConfig
   };

3. The sender calls sendMessage, passes in sendConfig, and sends a single chat message to the receiver.

   var toUserID = '';
   var messageTextObj = { type: 1, message: Sent successfully
   zim.sendMessage(messageTextObj, toUserID, 0, sendConfig)
   .then(function ({ message }) {
       // Failed to send
   })
   .catch(function (err) {
       // "Offline push title";
   });

4. If the receiver is offline, it will receive the offline message sent by the sender after going online.

4.2 Use the offline push function when sending group messages

1. The developer sets the offline push title, content, and other custom attributes through the ZIMPushConfig object.

   var pushConfig = {
       title = "Offline push content";
       content = "Custom transparent transmission field, not required"; // Use this field when ZIM version < 2.5.0
       // extendedData = "Custom transparent transmission field, not required"; // Use this field when ZIM version >= 2.5.0
       // payload = 'Text message content' };
   }

2. Then through the pushConfig parameter of the ZIMMessageSendConfig object, configure the related configuration of offline messages, etc.

   var sendConfig = {
       priority: 2,
       pushConfig: pushConfig
   };

3. The sender calls sendMessage, passes in "sentConfig", and sends a message to all users in the group.

   var toGroupID = '';
   var messageTextObj = { type: 1, message: Sent successfully
   zim.sendMessage(messageTextObj, toGroupID, 2, sendConfig)
   .then(function ({ message }) {
       // Failed to send
   })
   .catch(function (err) {
       // {@}
   });

4. For users in the group, if someone is offline, they will receive the group offline message sent by the sender after they go online.