实现离线推送

---

功能简介

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

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

方案介绍

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

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

2. APNs 推送服务器，将 DeviceToken 返回给接收方。

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 服务器将离线消息转发给 APNs 服务器。

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

前提条件

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

• 请确保开发环境满足以下要求：

  • Xcode 7.0 或以上版本。
  • iOS 11.0 或以上版本的 iOS 真机设备。
  • iOS 设备已经连接到 Internet。

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

实现流程

1 获取 APNs 推送证书

请参考 Apple 推送集成指南，获取 APNs 推送证书。

2 集成 ZPNs SDK

开发者可通过以下任意一种方式实现集成 SDK。

方式一： 使用 Swift Package Manager 自动集成

1. 打开 Xcode 并点击菜单栏 “File > Add Packages...”，在 “Apple Swift Packages” 弹窗的 “Search or Enter Package URL” 输入框中填写如下 URL 并敲击回车键确认：

   https://github.com/zegolibrary/zpns-ios

2. 在 “Dependency Rule” 中指定你想要集成的 SDK 版本（建议使用默认的 “Up to Next Major Version”），然后点击 “Add Package“ 导入 SDK。你也可以参考 Apple 官方文档 进行设置。

方式二：使用 CocoaPods 自动集成

1. 安装 CocoaPods，安装时的常见问题请参考 CocoaPods 常见问题 - 安装 CocoaPods。

2. 打开终端，进入项目根目录，执行 pod init 命令创建 Podfile 文件。

3. 打开 Podfile 文件，在 “target” 下添加 pod 'ZPNs'，需要将 “MyProject” 替换为开发者的 Target 名称。

   由于 SDK 为 XCFramework，只有 1.10.0 或以上版本的 CocoaPods 才能集成该 SDK。

   target 'MyProject' do
       use_frameworks!
       pod 'ZPNs'
   end

4. 执行 pod repo update 命令更新本地索引，确保能安装最新版本的 SDK，最新版本号请参考 发布日志。

5. 执行 pod install 命令安装 SDK。

   • 若出现 “CDN: trunk URL couldn't be downloaded” 问题，请参考 CocoaPods 常见问题 - 连接不上 trunk CDN 的问题。
   • 若出现 “Unable to find a specification for 'ZPNs'” 问题，请参考 CocoaPods 常见问题 - 无法找到项目的问题。
   • 若出现 “CocoaPods could not find compatible versions for pod "ZPNs"” 问题，请参考 CocoaPods 常见问题 - 无法找到项目的问题。

方式三：复制 SDK 文件手动集成

1. 请在 下载 获取最新的 SDK 包（包含 ZPNs SDK）。

2. 将 SDK 包解压至项目目录下，例如 “libs” 文件夹下。

3. 选择 “TARGETS > General > Frameworks,Libraries,and Embedded Content” 菜单，添加 “ZIM.xcframework”，将 “Embed” 设置为 “Embed & Sign”。

3 获取 DeviceToken

开发者需要获取 DeviceToken，ZIM SDK 才能根据 DeviceToken 配置离线推送功能。

3.1 添加头文件

首先在 AppDelegate.m 文件引入头文件。

import <ZPNs/ZPNs.h>

3.2 申请 App 的推送权限

开发者需要通过 requestAuthorizationWithOptions 官方接口，申请 App 的推送权限；即在发送离线消息时，手机设备上弹窗提示是否同意推送。

UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
center.delegate = (id)[ZPNs shared];
//请求获取通知权限（角标，声音，弹框）
[center requestAuthorizationWithOptions:(UNAuthorizationOptionBadge|UNAuthorizationOptionSound|UNAuthorizationOptionAlert) completionHandler:^(BOOL granted, NSError * _Nullable error) {
  if(granted){
      NSLog(@"用户允许发送通知");
  }
}];

3.3 获取 APNs 的 DeviceToken

1. 在 AppDelegate.m 文件中，开发者需要实现如下 Apple 官方的代理回调，用于接收 deviceToken。

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

}

2. 开发者调用 registerAPNs 注册 APNs，注册成功后，系统会通过 didRegisterForRemoteNotificationsWithDeviceToken 代理回调，自动获取到 DeviceToken。

[[ZPNs shared] registerAPNs];

3.4 ZPNs SDK 获取 DeviceToken

在 didRegisterForRemoteNotificationsWithDeviceToken 代理回调中，开发者需要通过 setDeviceToken 接口，获取到 DeviceToken。

// 使用 ZPNs SDK 获取 DeviceToken
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
/// Required - 注册 DeviceToken
//isProduct 根据是否是生产环境来填写
  [[ZPNs shared] setDeviceToken:devicetoken isProduct:false];
}

ZPNs SDK 获取到 DeviceToken 后，会把 DeviceToken 传给 ZIM SDK，ZIM SDK 会根据 DeviceToken 做相应的离线推送处理。

3.5 通过 onRegistered 获取 pushID

- (void)onRegistered:(NSString *)Pushid{

}

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

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

4.1 发送单聊消息时使用离线推送功能

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

   ZIMPushConfig *pushConfig = [ZIMPushConfig alloc] init];
   pushConfig.title = @"离线推送标题";
   pushConfig.content = @"离线推送内容";
   pushConfig.payload = @"自定义透传字段，非必填";
   pushConfig.resourcesID = @"资源ID";

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

   ZIMMessageSendConfig *sendConfig = [ZIMMessageSendConfig alloc] init];
   sendConfig.pushConfig = pushConfig;

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

   [zim sendPeerMessage:textMessage toUserID:@"toUserID" config:sendConfig callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
   
   }];

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

4.2 发送群组消息时使用离线推送功能

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

   ZIMPushConfig *pushConfig = [ZIMPushConfig alloc] init];
   pushConfig.title = @"离线推送标题";
   pushConfig.content = @"离线推送内容";
   pushConfig.payload = @"自定义透传字段，非必填";
   pushConfig.resourcesID = @"资源ID";

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

   ZIMMessageSendConfig *sendConfig = [ZIMMessageSendConfig alloc] init];
   sendConfig.pushConfig = pushConfig;

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

   [zim sendGroupMessage:textMessage toUserID:@"myGroupID" config:sendConfig callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
   
   }];

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

5 注销离线推送

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

[[ZPNs shared] unregisterAPNs];

在线调试

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