实现离线推送
本文档适用于开发 iOS 和 Android 端应用。
ZEGO 即时通讯(ZIM)支持离线推送消息的功能。例如在“单聊”或“群组聊天”时,如果您的程序在后台被冻结、或被系统或用户杀掉,与 ZEGO 服务后台的长连接超时断开后,此时如果您已接入“离线推送”功能,ZEGO 后台会为目标用户发送离线推送的消息。
开发者可以通过集成 ZPNs SDK,与 ZIM SDK 搭配使用,实现离线推送功能。
ZPNs uni-app SDK 需要搭配 ZIM uni-app SDK 2.2.0 或以上版本使用。
方案介绍
ZIM 实现离线推送的方案如下:
-
首先消息接收方(即接收离线消息的用户),开启各厂商的推送通道,向各厂商的推送服务器发送请求,获取 Token。
-
各厂商的推送服务器,将 Token 返回给接收方。
-
接收方生成 PushID,并向 ZIM 服务器发送请求,绑定用户与 PushID 的关系。
开发者如果将 ZPNs SDK 与 ZIM SDK 搭配使用,SDK 内部会自动绑定用户与 PushID 的关系,无需特殊处理;如果单独使用 ZPNs SDK,则需自行对接 ZPNs 服务器、实现绑定逻辑。请注意,同一设备切换 userID 前,请调用 zim.logout 接口,该接口会清除 userID 绑定的 PushID。
-
发送方开始发送消息,消息存储到 ZIM 服务器。
-
ZIM 服务器会确认接收方的客户端是否在线。
-
如果接收方的客户端不在线,ZIM 服务器会将消息转发给 ZPNs 服务器。
-
ZPNs 服务器将离线消息转发给各厂商的推送服务器。
-
各厂商的服务器将消息通过“离线推送”的方式,推送给接收方;接收方登录后(至少登录一次),即可收到离线消息。
前提条件
在实现“离线推送”功能之前,请确保:
- 开发环境满足以下要求:
- HBuilder X 3.0.5 或以上版本。
- iOS 12.0 或以上版本的 iOS 真机设备,暂不支持模拟器。
- Android 版本不低于 6.0 的 Android 设备,暂不支持模拟器。如果为真机,请开启“允许调试”选项。
- iOS/Android 设备已经连接到 Internet。
- 已在 ZEGO 控制台 创建项目,获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的,使用前,请先在 ZEGO 控制台 自助开通 ZIM 服务(详情请参考控制台的 服务配置 - 即时通讯 - 开通服务),若无法开通 ZIM 服务,请联系 ZEGO 技术支持开通。
- 已集成 ZIM SDK 2.1.5 或以上版本,详情请参考 快速开始 - 实现基本收发消息。
实现流程
接入第三方厂商离线推送通道
请参考下列推送集成指南,集成您需要的第三方厂商离线推送 SDK,接入各厂商的离线推送通道。集成方式会因为您的工程打包方式而有所差异。
目前支持 Apple、小米、华为、OPPO、vivo 和 Google 的推送。
离线打包
如果您根据 uni-app 提供的 APP 离线打包 方式打包(即 APP 工程在开发者本地),请参考下列推送集成指南全文,向厂商申请离线推送证书,在 ZEGO 控制台 配置离线推送证书,集成厂商的推送 SDK 等步骤。
云端打包
如果您使用 uni-app HBuilder 提供的云端打包方式,请参考下列推送集成指南的前提条件,向厂商申请离线推送证书,在 ZEGO 控制台 配置离线推送证书。
完成上述步骤,即可在集成 ZPNs uni-app SDK 时,自动集成上述厂商的推送 SDK。
- 为了保障 uni-app 在离线推送能力上获得最好的原生体验,建议您使用离线打包的方式进行接入第三方厂商离线推送通道。
- 由于 uni-app 云端打包因限制而无法适用于 FCM,因此,如需使用 FCM 请使用离线方式打包工程,并通过本地包手动集成 FCM 推送 SDK,详情请参考 FCM 推送集成指南。
- 如需实现进阶的 iOS 推送能力,如自定义通知图标、通知携带图片附件、替换通知能功能,请通过离线方式打包项目,而非云端打包方式。
集成 ZPNs SDK
导入 ZPNs SDK
-
请参考 下载 页面,获取最新版本的 ZPNs 原生插件 SDK,并解压得到的 “zego-ZPNsUniPlugin.zip” 文件。
-
将解压后获取的的文件夹,直接复制到您项目工程根目录下的 “nativeplugins” 文件夹,如果没有该目录,请手动创建。
注意由于 uni-app 原生插件的限制,ZPNs SDK 暂不支持通过插件市场下载插件,仅支持通过 ZEGO 官网下载获取。
-
单击项目目录的 “manifest.json” 文件后,单击 “App原生插件配置” 中的 “选择本地插件” 。
-
在弹出的选择框中,选择 “Zego ZPNs 离线推送 SDK” 后,单击“确认”,即添加成功。
-
(仅适用于云端打包项目)针对 vivo 推送,在 “App原生插件配置” 中,传入 vivo api_key 和 app_id,如图额外信息:
说明如何获取 vivo api_key 和 app_id,请参考 vivo 推送集成指南。
-
(仅适用于云端打包项目)由于接入华为推送需要在 App 的工程目录下增加
agconnect-services.json
文件,而云端打包的运行基座在 uni-app 厂商云端,那么这里就需要开发者在云端打包构建 apk 时上该文件。具体方法:打开 HBuilder,在
nativeplugins
目录下把刚集成进去的zego-ZPNsUniPlugin
目录里的android
子目录下,创建一个名为assets
的目录,然后把从华为开发中心里下载好的agconnect-services.json
拷贝进去即可。 -
(仅适用于云端打包项目)在 HBuilder > App模块配置中勾选使用 “Push” 推送模块。
注意不要勾选
uniPush
。
8.在 下载 取最新版本的 ZPNs JS 插件 SDK ,并解压得到的 “zego-ZPNsUniPlugin-JS.zip” 文件。
-
将解压后内容放至工程目录中的
js_sdk
目录下,若不存在该目录的情况下,请先创建该目录。
设置权限
开发者可以根据实际应用需要,设置应用所需权限。
-
iOS:
调用 applyNotificationPermission 接口,向用户申请通知权限。本接口仅第一次调用时生效,请开发者注意调用时机。
UntitledZPNs.getInstance().applyNotificationPermission();
1 -
Android:
Android 13 及以上的系统版本需要动态请求申请推送权限,可调用 applyNotificationPermission 接口,向用户申请通知权限。本接口仅第一次调用时生效,请开发者注意调用时机。
UntitledZPNs.getInstance().applyNotificationPermission();
1
使用 ZPNs SDK 注册离线推送功能
-
使用 ZPNsEventHandler 获取回调。
ZPNsEventHandler 类包含了 ZPNs 中各种事件回调的 Function,开发者可通过传入 Function 来接收 ZPNs 中的事件回调,处理 SDK 异常、消息通知回调。
各移动设备厂商对 ZPNsEventHandler 类的回调支持情况如下表所示:
接口名称 接口说明 厂商支持情况 registered 厂商注册“离线推送”的结果回调。厂商注册“离线推送”的结果,会统一在此接口抛出,可通过该回调获取到 PushID。 所有厂商都支持该回调。 notificationArrived 厂商通知展示回调。厂商通知展示回调,统一在此接口抛出。 - 苹果:支持该回调。
- 小米:App 处于前后台状态下才能收到此回调。
- 华为:不支持该回调。
- OPPO:不支持该回调。
- vivo:不支持该回调。
- Google: 不支持该回调。
throughMessageReceived 厂商透传消息回调。各厂商返回的透传消息都会触发该接口,并在此接口抛出通知。 - 苹果:暂不支持该回调
- 小米:不支持该回调。
- vivo:不支持该回调。
- 华为:支持该回调,但请先参考华为官方文档 推送服务 - FAQ - 申请特殊权限 申请 高优先级透传消息权限。
- OPPO:不支持该回调。
- Google:APP 处于前后台状态下才能收到此回调。
-
配置安卓第三方推送通道。
根据前提条件集成的第三方厂商离线推送 SDK,启用各厂商的推送功能,然后调用 setPushConfig 接口,配置第三方推送通道。
说明由于 Google FCM 的推送通道优先度更高,开启后会导致其他安卓厂商的推送通道失效,因此,如果您的 App 在中国大陆上线,请将 enableFCMPush 设置为
false
。反之,如果您的 App 运营于海外市场,则将其设置为true
。UntitledZPNs.setPushConfig({"enableFCMPush": false, "enableHWPush": true, "enableMiPush": true, "enableOppoPush": true, "enableVivoPush": true});
1 -
调用 enableDebug 设置当前项目的编译环境是否为 Debug,默认为 false。此操作是为了通知 ZPNs SDK 是否为 Debug 环境,PushID 的生成规则受此影响,请在调用 registerPush 接口前正确设置。
注意如果设置为 true,release 环境下无法收到推送。
UntitledZPNs.enableDebug(true);
1 -
调用 registerPush 接口注册离线推送。
说明- 在 iOS 端调用 registerPush 接口时,您需要根据打包时选择的证书为 development 还是 description 而提前填写
ZPNsIOSEnvironment
。切换证书时,请更改此枚举。 - 证书为 development 时,
ZPNsIOSEnvironment
为Development
。 - 证书为 distribution 时,
ZPNsIOSEnvironment
为Production
。 - 如果您尚不清楚当前所处的
ZPNsIOSEnvironment
,请填ZPNsIOSEnvironment.Automatic
。Automaic
可能受 iOS 系统版本影响,若 iOS 系统进行大版本更新后,请留意 ZPNs 发布日志是否存在相关更新说明。
Untitled// 在 iOS 调用 registerPush 接口时,iOSNotificationArrivedConfig 参数可以用来设置普通弹窗推送在前台到达时,是否展示弹窗、角标、声音,若希望不展示可不填。 ZPNs.getInstance().registerPush({iOSEnvironment:ZPNsIOSEnvironment.Automatic,iOSNotificationArrivedConfig:{isPresentAlert:true,isPresentSound:true,isPresentBadge:true}});
1注册离线推送功能后,可以通过 ZPNsEventHandler 类中的 registered 回调,获取到离线推送的
pushID
,向指定设备推送离线消息。 - 在 iOS 端调用 registerPush 接口时,您需要根据打包时选择的证书为 development 还是 description 而提前填写
使用 ZIM SDK 实现离线推送功能
ZIM 支持在发送单聊消息、群组消息和呼叫邀请时使用离线推送功能。
场景 1:发送单聊消息时使用离线推送功能
-
首先开发者需要通过 ZIMPushConfig 对象,设置离线推送标题、内容、以及其它自定义属性。
Untitledvar pushConfig = { title = "离线推送标题"; content = "离线推送内容"; // extendedData = "自定义透传字段,非必填"; // ZIM 版本 < 2.5.0 时使用该字段 // payload = "自定义透传字段,非必填"; // ZIM 版本 >= 2.5.0 时使用该字段 resourcesID = "资源 ID,非必填"; }
1 -
然后通过 ZIMMessageSendConfig 对象的
pushConfig
参数,配置离线消息的相关配置等。Untitledvar sendConfig = { priority: 2, pushConfig: pushConfig };
1 -
发送方调用 sendMessage,传入
sendConfig
,向接收方发送单聊消息。Untitledvar toUserID = ''; var messageTextObj = { type: 1, message: '文本消息内容' }; zim.sendMessage(messageTextObj, toUserID, 0, sendConfig) .then(function ({ message }) { // 发送成功 }) .catch(function (err) { // 发送失败 });
1 -
接收方如果处于离线状态,将会在上线后,接收到发送方之前发送的离线消息。
场景 2:发送群组消息时使用离线推送功能
-
开发者通过 ZIMPushConfig 对象,设置离线推送标题、内容、以及其它自定义属性。
Untitledvar pushConfig = { title = "离线推送标题"; content = "离线推送内容"; // extendedData = "自定义透传字段,非必填"; // ZIM 版本 < 2.5.0 时使用该字段 // payload = "自定义透传字段,非必填"; // ZIM 版本 >= 2.5.0 时使用该字段 resourcesID = "资源 ID,非必填"; }
1 -
然后通过 ZIMMessageSendConfig 对象的
pushConfig
参数,配置离线消息的相关配置等。Untitledvar sendConfig = { priority: 2, pushConfig: pushConfig };
1 -
发送方调用 sendMessage,传入 “sentConfig”,向群组内的所有用户发送消息。
Untitledvar toGroupID = ''; var messageTextObj = { type: 1, message: '文本消息内容' }; zim.sendMessage(messageTextObj, toGroupID, 2, sendConfig) .then(function ({ message }) { // 发送成功 }) .catch(function (err) { // 发送失败 });
1 -
群组内的用户,如果有人处于离线状态,将会在上线后,接收到发送方之前发送的群组离线消息。
场景 3:发送呼叫邀请时使用离线推送功能
-
开发者通过 ZIMPushConfig 对象,设置离线推送标题、内容、以及其它自定义属性。
Untitledvar pushConfig = { title = "离线推送标题"; content = "离线推送内容"; // extendedData = "自定义透传字段,非必填"; // ZIM 版本 < 2.5.0 时使用该字段 // payload = "自定义透传字段,非必填"; // ZIM 版本 >= 2.5.0 时使用该字段 resourcesID = "资源 ID,非必填"; }
1 -
然后通过 ZIMCallInviteConfig 对象的
pushConfig
参数,配置离线消息的相关配置等。Untitledvar callInviteConfig = { timeout: 90, pushConfig: pushConfig }
1 -
发送方调用 callInvite,传入 “callInviteConfig”,发起呼叫邀请。
Untitledvar invitees = ['xxxx']; // 被邀请人ID列表 zim.callInvite(invitees, callInviteConfig) .then(function({ callID, timeout, errorInvitees }){ // 操作成功 // 此处的 callID 是用户发起呼叫后,SDK 内部生成的 ID,用于唯一标识一次呼叫邀请;之后发起人取消呼叫、被邀请人接受/拒绝呼叫,都会使用此 callID }) .catch(function(err){ // 操作失败 })
1 -
被邀请的用户若处于离线状态,将会收到对应的离线推送,上线后,若呼叫邀请还未结束,将会收到 callInvitationReceived 回调。
注销离线推送
若开发者希望某台设备不再接收离线推送,可通过调用 unRegisterPush 接口注销。注销后,发送弹窗推送、静默推送也将不再生效。
ZPNs.getInstance().unregisterPush();
在线调试
集成 ZPNs SDK 和获取 Push ID 后,您可以在 ZEGO 控制台 在线调试 ZIM 离线推送功能,详情请参考控制台的 ZIM 离线推送调试。