实现离线推送

ZEGO 即时通讯（ZIM）支持离线推送消息的功能。例如在“单聊”或“群组聊天”时，如果您的程序在后台被冻结、或被系统或用户杀掉，与 ZEGO 服务后台的长连接超时断开后，此时如果您已接入“离线推送”功能，ZEGO 后台会为目标用户发送离线推送的消息。

开发者可以通过集成 ZPNs SDK，与 ZIM SDK 搭配使用，实现离线推送功能。

方案介绍

ZIM 实现离线推送的方案如下：

1. 首先消息接收方（即接收离线消息的用户），开启各厂商的推送通道，向各厂商的推送服务器发送请求，获取 Token。

2. 各厂商的推送服务器，将 Token 返回给接收方。

3. 接收方生成 PushID，并向 ZIM 服务器发送请求，绑定用户与 PushID 的关系。

   开发者如果将 ZPNs SDK 与 ZIM SDK 搭配使用，SDK 内部会自动绑定用户与 PushID 的关系，无需特殊处理；如果单独使用 ZPNs SDK，则需自行对接 ZPNs 服务器、实现绑定逻辑。请注意，同一设备切换 userID 前，请调用 zim.logout 接口，该接口会清除 userID 绑定的 PushID。

4. 发送方开始发送消息，消息存储到 ZIM 服务器。

5. ZIM 服务器会确认接收方的客户端是否在线。

6. 如果接收方的客户端不在线，ZIM 服务器会将消息转发给 ZPNs 服务器。

7. ZPNs 服务器将离线消息转发给各厂商的推送服务器。

8. 各厂商的服务器将消息通过“离线推送”的方式，推送给接收方；接收方登录后（至少登录一次），即可收到离线消息。

接入第三方厂商离线推送通道

请参考 Android 推送集成指南（小米/华为/OPPO/vivo/FCM），集成需要使用到的第三方厂商离线推送 SDK，接入各厂商的离线推送通道。

集成 ZPNs SDK

导入 ZPNs SDK

开发者有两种方式导入 ZPNs SDK：

• 方式1: 使用 Maven Central 自动集成 SDK
• 方式2: 复制 SDK 文件手动集成

设置权限

开发者可以根据实际应用需要，设置应用所需权限。

进入 “app/src/main” 目录，打开 “AndroidManifest.xml” 文件，添加权限。

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

使用 ZPNs SDK 注册离线推送功能

1. 开发者创建新的 Java 类 MyZIMPushReceiver 继承自 ZPNs 中的 ZPNsMessageReceiver 广播类，用于接收厂商推送消息。

   Untitled

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

   1

   Copied!

2. 实现继承 ZPNsMessageReceiver 的广播中的函数，用于向厂商发送相关通知。其中，

   关于各大厂商的回调支持情况：

   接口名称	接口说明	厂商支持情况
   onThroughMessageReceived	厂商透传消息回调。各厂商返回的透传消息都会触发该接口，并在此接口抛出通知。	小米：不支持该回调 vivo：不支持该回调 华为：支持该回调，但请先参考华为官方文档 推送服务 - FAQ - 申请特殊权限 申请高优先级透传消息权限 谷歌推送：APP 处于前后台状态下才能收到此回调 OPPO：不支持该回调
   onNotificationArrived	厂商通知展示回调。厂商通知展示回调，统一在此接口抛出。	小米 处于前后台状态下才能收到此回调 vivo：不支持该回调 华为：不支持该回调 谷歌推送：不支持该回调 OPPO：不支持该回调
   onRegistered	厂商注册“离线推送”的结果回调。厂商注册“离线推送”的结果，会统一在此接口抛出，可通过该回调获取到 PushID。	所有厂商都支持

   Untitled

   public class MyZPNsReceiver extends ZPNsMessageReceiver {
       // 厂商透传消息回调
       @Override
       protected void onThroughMessageReceived(Context context, ZPNsMessage message) {
           Log.e("MyZPNsReceiver", "onThroughMessageReceived message:" + message.toString());
       }
   
       // 厂商通知展示回调
       @Override
       protected void onNotificationArrived(Context context, ZPNsMessage message) {
           Log.e("MyZPNsReceiver", "onNotificationArrived message:" + message.toString());
       }
   
       // 厂商注册离线推送结果回调，可通过该回调获取到 Push ID
       @Override
       protected void onRegistered(Context context, ZPNsRegisterMessage message) {
           Log.e("MyZPNsReceiver", "onRegistered: message:" + message.getCommandResult());
       }
   }
   

   1

   Copied!

3. 配置第三方推送通道。

   根据 前提条件 集成的第三方厂商离线推送 SDK，调用 enableHWPush/enableMiPush/enableOppoPush/enableVivoPush 接口，启用各厂商的推送功能，然后调用 setPushConfig 接口，配置第三方推送通道。

   Untitled

   ZPNsConfig zpnsConfig = new ZPNsConfig();
   zpnsConfig.enableFCMPush(); // FCM
   zpnsConfig.enableHWPush("HW_APP_ID"); // 华为
   zpnsConfig.enableMiPush("MI_APPID", "MI_APPKEY"); // 小米
   zpnsConfig.enableOppoPush("OPPO_APP_ID", "OPPO_APP_KEY", "OPPO_APP_SECRET"); // OPPO
   zpnsConfig.enableVivoPush("VIVO_APP_ID", "VIVO_APP_KEY"); // vivo
   ZPNsManager.setPushConfig(zpnsConfig);
   

   1

   Copied!

4. 注册离线推送功能。

   Untitled

   ZPNsManager.getInstance().registerPush(this.getApplication());
   

   1

   Copied!

   注册离线推送功能后，可以通过继承 ZPNsMessageReceiver 类中的 onRegistered 回调，获取到离线推送的 pushID，向指定设备推送离线消息。

5. 如果不再需要离线推送功能，开发者可以调用 unregisterPush 接口，注销该功能，注销后用户将不再能收到推送消息。

   Untitled

   ZPNsManager.getInstance().unregisterPush();
   

   1

   Copied!

使用 ZIM SDK 实现离线推送功能

ZIM 支持在发送单聊消息、发送群组消息、发起呼叫邀请时，使用离线推送消息的功能。

场景 1：发送单聊消息时使用离线推送功能

1. 首先开发者需要通过 ZIMPushConfig 对象，设置离线推送标题、内容、以及其它自定义属性。

   Untitled

   ZIMTextMessage textMessage = new ZIMTextMessage();
   ZIMPushConfig pushConfig = new ZIMPushConfig();
   pushConfig.title = "离线推送标题";
   pushConfig.content = "离线推送内容";
   pushConfig.payload = "自定义透传字段，非必填";
   pushConfig.resourcesID = "资源 ID，非必填";
   

   1

   Copied!

2. 然后通过 ZIMMessageSendConfig 对象的 pushConfig 参数，配置离线消息的相关配置等。

   Untitled

   ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig();
   sentConfig.pushConfig = pushConfig;
   

   1

   Copied!

3. 发送方调用 sendMessage，传入 “sentConfig”，向接收方发送单聊消息。

   Untitled

   zim.sendMessage(textMessage, "myUserID", ZIMConversationType.PEER, sentConfig, new ZIMMessageSentCallback() {
        @Override
        public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
   
        }
   
        @Override
        public void onMessageAttached(ZIMMessage message) {
   
        }
   });
   

   1

   Copied!

4. 接收方如果处于离线状态，将会在上线后，接收到发送方之前发送的离线消息。

场景 2：发送群组消息时使用离线推送功能

1. 开发者通过 ZIMPushConfig 对象，设置离线推送标题、内容、以及其它自定义属性。

   Untitled

   ZIMTextMessage textMessage = new ZIMTextMessage();
   ZIMPushConfig pushConfig = new ZIMPushConfig();
   pushConfig.title = "离线推送标题";
   pushConfig.content = "离线推送内容";
   pushConfig.payload = "自定义透传字段，非必填";
   pushConfig.resourcesID = "资源 ID，非必填";
   

   1

   Copied!

2. 然后通过 ZIMMessageSendConfig 对象的 pushConfig 参数，配置离线消息的相关配置等。

   Untitled

   ZIMMessageSendConfig sentConfig = new ZIMMessageSendConfig();
   sentConfig.pushConfig = pushConfig;
   

   1

   Copied!

3. 发送方调用 sendMessage，传入 “sentConfig”，向群组内的所有用户发送消息。

   Untitled

   zim.sendMessage(textMessage, "myGroupID", ZIMConversationType.GROUP, sentConfig, new ZIMMessageSentCallback() {
        @Override
        public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
   
        }
        
        @Override
        public void onMessageAttached(ZIMMessage message) {
   
        }
   });
   

   1

   Copied!

4. 群组内的用户，如果有人处于离线状态，将会在上线后，接收到发送方之前发送的群组离线消息。

场景 3：发送呼叫邀请时使用离线推送功能

1. 开发者通过 ZIMPushConfig 对象，设置离线推送标题、内容、以及其它自定义属性。

   Untitled

   ZIMPushConfig pushConfig = new ZIMPushConfig();
   pushConfig.title = "离线推送标题";
   pushConfig.content = "离线推送内容";
   pushConfig.payload = "自定义透传字段，非必填";
   pushConfig.resourcesID = "资源 ID，非必填";
   

   1

   Copied!

2. 然后通过 ZIMCallInviteConfig 对象的 pushConfig 参数，配置离线消息的相关配置等。

   Untitled

   ZIMCallInviteConfig callInviteConfig = new ZIMCallInviteConfig();
   callInviteConfig.pushConfig = pushConfig;
   

   1

   Copied!

3. 发送方调用 callInvite，传入 “ callInviteConfig”，发起呼叫邀请。

   Untitled

   ArrayList<String> invitees = new ArrayList<>();
   invitees.add("userA");
   invitees.add("userB");
   zim.callInvite(invitees, callInviteConfig, new ZIMCallInvitationSentCallback() {
       @Override
       public void onCallInvitationSent(String callID, ZIMCallInvitationSentInfo info, ZIMError errorInfo) {
       }
   });
   

   1

   Copied!

4. 被邀请的用户若处于离线状态，将会收到对应的离线推送，上线后，若呼叫邀请还未结束，将会收到 onCallInvitationReceived 的回调。

在线调试

集成 ZPNs SDK 和获取 Push ID 后，您可以在 ZEGO 控制台 在线调试 ZIM 离线推送功能，详情请参考控制台的 ZIM 离线推送调试。