- Documentation
- In-app Chat
- Offline push notifications
- Implement offline push notification
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 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 thebuild.gradle
file.A. Add a
sourceSets
node in theandroid
node, and specify the directory where thelibs
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 thedependencies
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 classZPNsMessageReceiver
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 classZPNsMessageReceiver
, 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 thesetPushConfig
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 classZPNsMessageReceiver
, and get thepushID
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 theZIMMessageSendConfig
object.ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig(); sentConfig.pushConfig = pushConfig;
The message sender calls the
sendPeerMessage
method with thesendConfig
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 theZIMMessageSendConfig
object.ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig(); sentConfig.pushConfig = pushConfig;
The message sender calls the
sendGroupMessage
method with thesendConfig
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.