Implement offline push notification

2026-04-02

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.

Warning

The ZPNs SDK must be used with ZIM SDK 2.0.0 or later.

Solution

The solution we provide is as follows:

The receiver (i.e., the user receiving offline messages) enables the push channels of Google FCM, sends requests to the Google FCM push server, and obtains tokens.
The push servers return tokens.
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 Google FCM push server.
The Google FCM service pushes the offline push notifications to the receiver. The receiver receives the offline messages when gets back online.

Access Google FCM

To implement the offline push notification feature, you need to access Google FCM. For more, refer to Integrate Google FCM push notification (Android).

Integrate the ZPNs SDK

Import the ZPNs SDK

Developers have two ways to import ZPNs SDK:

Method 1: Automatically Integrate SDK Using Maven Central
Method 2: Manual Integration by Copying SDK Files

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" />

<!-- Permissions required by the ZPNs SDK. -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Set up the offline push notification

Create a new Java class MyZIMPushReceiver that extends the ZPNsMessageReceiver broadcast class in ZPNs, used for receiving push messages from Google FCM.

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

<receiver
    android:name=".MyZPNsReceiver"
    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 Google FCM.

onThroughMessageReceived: Callback for passing the notifications directly. For Google FCM, The callback can only be received when the APP is in the foreground or background.
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 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());
    }
}

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 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());
    }
}

Expand to learn how to retrieve the payload passthrough field

Refer to the following code to retrieve the payload field from the ZPNsMessage object when the ZPNsMessageReceiver callback method is triggered.

static public String getZPNsMessagePayload(ZPNsMessage message){
    String payload = "";
    switch (message.getPushSource()){
        case FCM:
            com.google.firebase.messaging.RemoteMessage remoteMessage = (com.google.firebase.messaging.RemoteMessage)message.getExtras();
            payload = remoteMessage.getData().get("payload");
            break;
    }
    return payload;
}

static public String getZPNsMessagePayload(ZPNsMessage message){
    String payload = "";
    switch (message.getPushSource()){
        case FCM:
            com.google.firebase.messaging.RemoteMessage remoteMessage = (com.google.firebase.messaging.RemoteMessage)message.getExtras();
            payload = remoteMessage.getData().get("payload");
            break;
    }
    return payload;
}

Configure the Google FCM push notification channel.

After access the Google FCM SDK as described above, call the enableFCMPush method to enable the Google FCM push notification service, and then call the setPushConfig method to configure the push notification channel.
```
ZPNsConfig zpnsConfig = new ZPNsConfig();
zpnsConfig.enableFCMPush(); // FCM
zpnsManager.setPushConfig(zpnsConfig);
```
```
ZPNsConfig zpnsConfig = new ZPNsConfig();
zpnsConfig.enableFCMPush(); // FCM
zpnsManager.setPushConfig(zpnsConfig);
```
Set up the offline push notification feature.
```
ZPNsManager.getInstance().registerPush(this.getApplication());
```
```
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.

Unregister offline push notification

If you no longer need the offline push notification feature, developers can call the unregisterPush interface to cancel this feature, and users will no longer receive push messages after it is canceled successfully.

ZPNsManager.getInstance().unregisterPush();

ZPNsManager.getInstance().unregisterPush();

Implement offline push notifications with the ZIM SDK

2026-04-02

For details, refer to Implementing Offline Push Notifications with the ZIM SDK.