实现离线推送

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

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

方案介绍

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

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

2. HarmonyOS 推送服务器，将 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 服务器将离线消息转发给 HarmonyOS 推送服务器。

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

前提条件

在实现“离线推送”功能之前，请确保：

• 开发环境满足以下要求：
  • DevEco Studio 版本：DevEco Studio 5.0.0 Release（5.0.3.910）或以上版本。
  • 测试设备为安装 HarmonyOS 5.0.0 Release 或以上版本的真机，或 ARM 模拟器。
  • 设备已经连接到 Internet。
• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息。

实现流程

开通 HarmonyOS 推送服务

详情请参考 HarmonyOS 推送集成指南。

集成 ZPNs SDK

1

获取 SDK

请在 下载 获取 ZPNs SDK 压缩包。

2

解压 SDK

解压 SDK 至 “entry/libs” 项目目录下。

说明

如果您的项目中没有 libs 目录，手动新建一个即可。

3

添加 SDK 引用

打开 entry/oh-package.json5 文件，在 dependencies 节点中引入 “libs” 下的 ZPNs.har。

entry/oh-package.json5

"@zego/ZPNs": "file:./libs/ZPNs.har"

entry/oh-package.json5

"@zego/ZPNs": "file:./libs/ZPNs.har"

导入 ZPNs SDK

在需要使用 ZPNs 功能的文件中，导入 ZPNs 模块，以便访问和使用它提供的功能或接口。

import ZPNs from '@zego/ZPNs'

import ZPNs from '@zego/ZPNs'

设置权限

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

调用 requestEnableNotification 接口，向用户申请通知权限。本接口仅第一次调用时生效，请开发者注意调用时机。

import { notificationManager } from '@kit.NotificationKit';

// !mark
notificationManager.requestEnableNotification(this.context).then((res) => {
    hilog.info(0x0000, 'testTag', 'Permission granted');

}).catch((err:BusinessError) => {
    hilog.info(0x0000, 'testTag', 'Permission failed. err code: %{public}d, err msg: %{public}s', err.code, err.message);
    if(err.code == 1600004) {
        notificationManager.openNotificationSettings(this.context).then((res) => {

        }).catch((err:BusinessError) => {
            hilog.info(0x0000, 'testTag', 'Open settings page failed. err code: %{public}d, err msg: %{public}s', err.code, err.message);
        });
    }

});

import { notificationManager } from '@kit.NotificationKit';

// !mark
notificationManager.requestEnableNotification(this.context).then((res) => {
    hilog.info(0x0000, 'testTag', 'Permission granted');

}).catch((err:BusinessError) => {
    hilog.info(0x0000, 'testTag', 'Permission failed. err code: %{public}d, err msg: %{public}s', err.code, err.message);
    if(err.code == 1600004) {
        notificationManager.openNotificationSettings(this.context).then((res) => {

        }).catch((err:BusinessError) => {
            hilog.info(0x0000, 'testTag', 'Open settings page failed. err code: %{public}d, err msg: %{public}s', err.code, err.message);
        });
    }

});

注册离线推送

ZPNs.getInstance().on("registered",(message:ZPNsRegisterMessage)=>{
    console.log("code:"+message.errorCode+"message:"+message.msg+" push id:"+message.pushID)
})

ZPNs.getInstance().on("registered",(message:ZPNsRegisterMessage)=>{
    console.log("code:"+message.errorCode+"message:"+message.msg+" push id:"+message.pushID)
})

try {
    ZPNs.getInstance().registerPush({})
} catch (e) {
    console.log("registerPush failed with exception:"+e)
}

try {
    ZPNs.getInstance().registerPush({})
} catch (e) {
    console.log("registerPush failed with exception:"+e)
}

注销离线推送

若开发者希望某台设备不再接收离线推送，可通过调用 unRegisterPush 接口注销。注销后，发送弹窗推送、静默推送也将不再生效。

ZPNs.getInstance().unregisterPush();

ZPNs.getInstance().unregisterPush();

使用 ZIM SDK 实现离线推送

请参考 使用 ZIM SDK 实现离线推送。

在线调试

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