Documentation
In-app Chat
Offline push notifications
Implement offline push notification

Implement offline push notification

Last updated：2023-05-11 14:25

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 notifications feature.

Solution

The solution we provide is as follows:

The receiver (the client user that receives the offline push notifications) enables the APNs channel, and sends a request to get the DeviceToken from the Push Notification Service provided by other vendors.
The Push Notification Service provided by other vendors returns the DeviceToken.
The receiver generates a PushID, and sends it to the ZIM Server for binding the client user and PushID.

If you use the ZPNs SDK together with the ZIM SDK, the SDK will automatically bind the client user to PushID, you don't need to do other operations; If you use the ZPNs SDK alone, you will need to connect to the ZPNs server and implement the binding logic. 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 APNs Server.
The Push Notification Service provided by other vendors pushes the offline push notifications to the receiver. The receiver receives the offline messages when gets back online.

Prerequisites

Create a project in ZEGOCLOUD Console. Then, contact Technical Support to activate the In-app Chat service, and get the AppID and ServerSecret for SDK integration. The ZIM service permission is not enabled by default. Before using it, please activate the ZIM service by yourself in ZEGOCLOUD Console (for details, please refer to Project Management - In-app Chat), if you cannot activate the ZIM service, please contact ZEGOCLOUD technical support to activate it.
Get the Token that SDK required for login authentication. For details, see Authentication.
Integrate the ZIM SDK. For details, see the Integrate the SDK chapter of Send and receive messages.

Android Studio 2.1 or later
Android SDK Packages: Android SDK 25, Android SDK Build-Tools 25.0.2, Android SDK Platform-Tools 25.x.x or later.
An Android device or Simulator that is running on Android 4.4 or later and supports audio and video. We recommend you use a real device.

Access the third party's push notification service

To implement the offline push notification feature, you will need to access the third party's push notification service. To know how to access the service, refer to the official documentation of the vendors (XIAOMI, HUAWEI, OPPO, Vivo).

Integrate the ZPNs SDK

Import the ZPNs SDK

Download the latest version of the SDK (the ZPNs SDK included).
Extract the downloaded SDK package to the app/libs folder.
Import the SDK. Go to the app directory, open the build.gradle file.

A. Add a sourceSets node in the android node, and specify the directory where the libs locates.

The libs directory is only for demonstration. You need to fill in the actual path.
```
sourceSets {
    main {
        jniLibs.srcDirs = ['libs']
    }
}
```
B. Import all .jar files under the libs directory to the dependencies node.
```
implementation fileTree(dir: 'libs', include: ['*.jar'])
```

Set permissions

Permissions can be set as needed.

Navigate to the app/src/main directory, open the AndroidManifest.xml file to add permissions.

<!-- Permissions required by the 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" />

Set up the offline push notification feature using the ZPNs SDK

Configure a receiver that inherits the class ZPNsMessageReceiver to receive the notifications pushed by vendors.

<receiver
    android:name="com.zego.PushPlayground2.MyZIMPushReceiver"
    android:enabled="true"
    android:exported="true">
        <intent-filter>
            <action android:name="im.zego.zim.zpns.intent.action.MESSAGE" />
        </intent-filter>
    </receiver>

Implement the callbacks in the receiver that has inherited the class ZPNsMessageReceiver, which can be used to send related notifications to service vendors.

onThroughMessageReceived: Callback for passing the notifications directly.
onNotificationClicked: Callback for clicking the notifications.
onNotificationArrived: Callback for displaying the notifications.

onRegistered: Callback for the results of setting up the offline push notifications, this can be used to get the Push ID.

public class MyZPNsReceiver extends ZPNsMessageReceiver {
  // Callback for passing the notifications directly. 
  @Override
  protected void onThroughMessageReceived(Context context, ZPNsMessage message) {
      Log.e("MyZPNsReceiver", "onThroughMessageReceived message:" + message.toString());
  }

  // Callback for clicking the notifications. 
  @Override
  protected void onNotificationClicked(Context context, ZPNsMessage message) {
      Log.e("MyZPNsReceiver", "onNotificationClicked message:" + message.toString());
  }

  // Callback for displaying the notifications. 
  @Override
  protected void onNotificationArrived(Context context, ZPNsMessage message) {
      Log.e("MyZPNsReceiver", "onNotificationArrived message:" + message.toString());
  }

  // Callback for the results of set up the offline push notifications, this can be used to get the Push ID.
  @Override
  protected void onRegistered(Context context, ZPNsRegisterMessage message) {
      Log.e("MyZPNsReceiver", "onRegistered: message:" + message.getCommandResult());
  }
}

Configure a push notification channel.

After integrating the SDK according to the Prerequisites steps, call the enableHWPush/enableMiPush/enableOppoPush/enableVivoPush method to enable the Push Notification Service provided by third-party vendors, and then call the setPushConfig method to configure a push notification channel.
```
ZPNsConfig zpnsConfig = new ZPNsConfig();
zpnsConfig.enableHWPush(true); // HUAWEI
zpnsConfig.enableMiPush(true); // XIAOMI
zpnsConfig.enableOppoPush(true); // OPPO
zpnsConfig.enableVivoPush(true); // vivo
zpnsManager.setPushConfig(zpnsConfig);
```
Set up the offline push notification feature.
```
ZPNsManager.getInstance().registerPush(this.getApplication());
```
After setting up the offline push notification feature, inherit the callback onRegistered of the class ZPNsMessageReceiver, and get the pushID to push offline push notifications to specified devices.
After finishing using this feature, call the unregisterPush method to cancel this feature. Users can't receive any notifications after it is canceled successfully.
```
ZPNsManager.getInstance().unregisterPush();
```

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.

Send one-on-one messages with offline push notification

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

ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "offline push notification title";
pushConfig.content = "offline push notification content";
pushConfig.through = "Customizable field, optional.";

Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.
```
ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig();
sentConfig.pushConfig = pushConfig;
```

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

zim.sendPeerMessage(textMessage, "myUserID", sentConfig, new ZIMMessageSentCallback() {
     @Override
     public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {

     }
});

The 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.

ZIMTextMessage textMessage = new ZIMTextMessage();
ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "offline push notification title";
pushConfig.content = "offline push notification content";
pushConfig.through = "Customizable field, optional.";

Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.
```
ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig();
sentConfig.pushConfig = pushConfig;
```

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

zim.sendGroupMessage(textMessage, "myUserID", sentConfig, new ZIMMessageSentCallback() {
     @Override
     public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {

     }
});

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

ZEGO UIKits

Cloud Communications Products

Low-Code Products

AIGC

Supporting Services