集成 APNs 远程推送
融云服务端已集成 APNs 服务端功能。当 App 被杀进程，或者在后台被挂起，或者在后台存活超过 2 分钟，SDK 长连接通道会断开，此时融云服务端可将消息通过 APNs 通道通知客户端。
融云服务端对 APNs 的支持
融云服务端支持与 Apple APNs 服务端的以下验证方式：
| 类别 | 区别 | 必要凭证 |
|---|---|---|
| 使用验证令牌（P8） | APNs 侧对基于令牌的推送请求处理更快。同一帐户下的应用程序可以使用同一个 P8 证书，不区分沙盒与生产环境。P8 证书永久有效。 | 您需要从 Apple 开发人员账户中获取签名密钥（.p8 后缀的文本文件），并提供给融云。融云将使用您的密钥对 APNs 推送请求中的 Token 进行签名。 |
| 使用 TSL 证书（P12） | 必须与 Apple App ID 绑定，仅可用于该 App。APNs 证书可以只支持沙盒环境（P12 证书），同时支持生产环境和沙盒环境（P12 通用证书）。有效期一年。 | 您可以从 Apple 开发人员账户获取该证书，并提供给融云。融云将使用该证书与 APNs 进行身份验证。证书在一年后过期，请务必在过期前创建新证书，然后将其提供给融云。 |
以上内容摘自 Apple 官方开发者文档。如有疑问，详见 Apple 开发者帐户帮助：使用验证令牌与 APNs 通信 与 使用 TLS 证书与 APN 通信。
下图以使用 TSL 证书为例，说明融云离线消息触发 APNs 推送的流程：
Apple 开发者账户的操 作
您必须持有 App ID 才能使用 APNs 推送服务。以下描述了如何从 Apple 开发者账户页面创建 App ID，以及为 App ID 启用 Push Notifications（推送通知功能）。
创建 App ID
如已持有 App ID，请跳过此步骤，直接查看启用 App ID 的推送功能。
以下步骤描述如何从 Apple 开发者账户创建 App ID：
-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后点按左上方的添加按钮 (+)。
-
从选项列表中选择 App IDs（App ID），点按 Continue（继续）。
-
从选项中，确认已自动选择了 App ID 类型，然后点按 Continue（继续）。
-
在 Description（描述）栏位中输入 App ID 的名称或描述。请选择 Explicit App ID （精确 App ID），并在 Bundle ID 栏位中输入 App 的 Bundle ID。
您在这里输入的精确 App ID 应该与 Xcode 中目标的 Summary （摘要）面板中输入的 Bundle ID 一致。
-
Capabilities （功能）下面会显示您的 App 类型和可以使用的功能。选中相应的复选框，以启用您想要使用的 App 功能。
请勾选 Push Notifications 以启用推送通知功能。
-
点按 Continue（继续），检查注册信息，然后点按 Register（注册）。
关于上述创建 App ID 步骤的详细说明，可参考 Apple 开发者帐户帮助文档：注册 App ID。
启用 App ID 的推送功能
以下内容来自 Apple 开发者账户帮助文档： 启用推送通知。
以下步骤描述如何从 Apple 开发者账户为已有的 App ID 启用推送通知功能。如已启用，可跳过该步骤。
-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后找到对应的 App ID 进行配置。
-
在 Capabilities 中勾选 Push Notifications。
启用 App ID 的推送功能后，请根据需要选择创建 P8 证书或者 P12 证书。
使用验证令牌（P8）
如需了解 “使用验证令牌与 APNs 通信”，可参见 Apple 开发者文档 Establishing a Token-Based Connection to APNs。以下步骤来自 Apple 开发者账户帮助文档： 创建并下载启用了 APNs 的私钥。
您需要从 Apple 开发人员账户中创建并下载用于 APNs 推送服务的私钥（.p8 后缀的文本文件，也称为 “P8 证书”）。
-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Keys (密钥)，再点按左上方的添加按钮 (+)。
-
在 Key Name（密钥名称）下面，为密钥输入唯一的名称。勾选 Apple Push Notifications service (APNs)，以启用 APNs 服务，再点按 Continue（继续）。
-
检查密钥配置，再点击 Confirm。
-
点按 Download（下载），立即生成并下载密钥文件。密钥会以文件扩展名为
.p8的文本文件形式下载到本地。- 注意：请记录下 Key ID，后续需要使用。
- 警告：密钥只可下载一次，下载后将从您的开发者帐户中移除，因此请务必妥善保管。如果 Download（下载）按钮处于停用状态，则表示您已经下载过这个密钥。
-
点按 Done（完成）。
获取 .p8 文件后，您可以前往融云控制台上传文件。详见上传证书到融云。
使用 TSL 证书（P12）
如需了解 p12 证书及“使用 TLS 证书与 APNs 通信”，可参见 Apple 开发者文档 Establishing a Certificate-Based Connection to APNs。
创建 p12 证书需要先从本地创建证书签名请求 (CSR)，再前往 Apple 开发者账户 上传 CSR 生成证书（.cer）文件，下载到本地，在 Mac 上导出为 .p12 格式的证书。
创建证书签名请求
Mac 上的“钥匙串访问”让您可以创建证书签名请求 (CSR)。
-
打开 Mac 应用中的钥匙串访问，选择证书助理，再选择从证书颁发机构请求证书。
-
填写证书信息，并保存到磁盘。
- 在证书助理对话框中，在“用户电子邮件地址”栏位中输入电子邮件地址。
- 在常用名称栏位中，输入密钥的名称 (例如，RongCloud)。
- 将 CA 电子邮件地址栏位留空。
- 选取存储到磁盘， 然后点按继续。
生成 cer 格式证书
如有多个 App，则需要为每个 App 生成单独的客户端 TLS 证书。
本步骤描述如何从 Apple 开发者账户生成 .cer 后缀的推送证书。注意，本步骤创建的 .cer 文件必须转换为 .p12 后缀的文件后才能在融云控制台上传使用。
以下两种方式仅存在 UI 操作上的区别，任选一种即可。
-
方式一：从 Apple 开发账户的 Certificates（证书）页面操作，生成
.cer文件。-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Certificates (证书)，然后点按左上方的添加按钮 (+)。
-
选择证书种类，点按 Continue（继续）。
- Apple Push Notification service SSL（Sandbox）：仅可向 APNs Sandbox 环境推送。仅可在融云控制台的环境使用此类证书，生产环境不允许使用此类证书。
- Apple Push Notification service SSL（Sandbox & Production）：可向 APNs Sandbox 和 Production 环境推送，可在融云应用的开发环境和生产环境中使用。
-
选择需要生成证书的 App ID，点按 Continue（继续）。
-
在 Mac 上创建证书签名请求。如果您已按上文指导创建了 CSR 文件，可跳过这一步。
-
点击 Choose File（选取文件），将生成的请求证书（CSR文件）上传，点按 Continue（继续）。
-
点击 Download 将证书下载到本地。
-
-
方式二：从 Apple 开发账户的 Identifiers (标识符)页面操作，生成
.cer文件。提示-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后选择要设置的 App ID。
-
在 Capabilities（功能）下，确认已选中 Push Notifications （推送通知）复选框。
-
点按 Configure（配置），进入创建证书页面。选择需要配置证书的环境，点按 Create Certificate（创建证书）。APNs 提供生产与开发两个环境。
- Development SSL Certificate：仅可向 APNs Sandbox 环境推送。仅可在融云控制台的环境使用此类证书，生产环境不允许使用此类证书。
- Production SSL Certificate：可向 APNs Sandbox 和 Production 环境推送，可在融云应用的开发环境和生产环境中使用。
-
在 Mac 上创建证书签名请求。如果您已按上文指导创建了 CSR 文件，可跳过这一步。
-
点击 Choose File（选取文件），将生成的请求证书（CSR文件）上传，点按 Continue（继续）。
-
点击 Download 将证书下载到本地。
-
转换 cer 文件为 P12 格式证书
-
双击下载到本地的证书文件（
.cer），证书会自动导入钥匙串中。证书的名称为Apple [Development/Production] iOS Push Services: [Bundle ID]，或者Apple Push Services: [Bundle ID]。 -
在 Mac 应用 钥匙串访问 中，左侧点击 登陆 和 证书，选择刚导入的证书，右键导出为扩展名为
.p12的证书文件。
-
系统将显示一个对话框，提示输入将用于保护导出项目的密码。您在此输入的密码将在后续将 p12 证书上传到融云后台时使用，请务必记录该密码。
-
再输入一次证书密码，执行导出操作。
在融云控制台配置 APNs 推送
您需要将创建的 APNs Auth Key 文件（P8）或者 TSL 证书（P12）上传到融云后台，融云服务端才能与 APNs 通信，向 iOS 客户端发送推送通知。
-
前往 融云控制台，点击 应用标识 并找到当前需要集成的项目，然后点击 设置推送。如果未创建可点击 添加。
-
填写 Bundle Identifier。
-
如果您创建了 P8 证书文件，鉴权方式请选择 Token Authentication。具体步骤如下：
-
点击上传 P8 文件，选择您创建的 APNs 签名密钥
.p8文件。
-
填写 Key ID（参见创建 p8 证书）。
-
填写 Team ID。您可以在 Apple 开发者账户 的 Membership 页面获取 Team ID。
-
-
如果您创建了 P12 证书文件，请注意融云应用的生产环境仅接受 APNs 通用证书（Sandbox & Production）。请根据证书类型和当前环境选择合适的鉴权方式：
- 如果上传 APNs 开发证书（Sandbox），请选择 P12 证书。
- 如果上传 APNs 通用证书（Sandbox & Production），请选择 P12 通用证书。
- 上传证书，填写证书密码。
- 如果在融云应用的开发环境中使用 APNs 通用证书（Sandbox & Production），请在推送环境中向 APNs 的 Sandbox 或 Production 环境推送。在生产环境使用 APNs 通用证书时，仅支持推送到 APNs 的 Production 环境，无需选择。
创建 Provisioning Profile 文件
您需要创建一个 Provisioning Profile（配置文件），才能在设备上运行您的应用程序，使用推送通知功能。您需要从 Apple 开发者账户创建并下载预置描述文件，然后在 Xcode 中安装预置描述文件。
-
在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Profiles (标识符)，然后点按左上方的添加按钮 (+)。
-
选择 Provisioning Profile 的环境后点按 Continue
-
选择要创建 Provisioning Profile 的 App ID 后，点按 Continue。
-
选择所属的开发者证书, 如果创建了多个，选择 Select All，点按 Continue。
-
为该 Provisioning Profile 选择将要安装的设备（一般选择 Select All），点按 Continue。
-
填写 Profile Name。建议命名为环境 + AppID，点击 generate 完成创建。
-
创建成功后，点击 Download 下载到本地。
-
双击下载的 Provisioning Profile 文件，添加到 Xcode。
客户端配置
请求推送权限
无论是本地推送还是远程推送，都需要申请权限。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
if ([[UIDevice currentDevice].systemVersion floatValue] >= 10.0) {
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
center.delegate = self;
[center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionBadge | UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error) {
if (granted) {
//点击允许
[center getNotificationSettingsWithCompletionHandler:^(UNNotificationSettings * _Nonnull settings) {
}];
} else {
}
}];
}else if ([[UIDevice currentDevice].systemVersion floatValue] >8.0){
//iOS8 - iOS10
[application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeSound | UIUserNotificationTypeBadge categories:nil]];
}
}
用户同意后，还需要在用户设备上获取 device token。融云服务器可以使用这个 token 将用向 Apple Push Notification 的服务器提交请求，然后 APNs 通过 token 识别设备和应用，将通知推给用户。
-
iOS 10 及以后，向 APNs 推送服务注册，以获取 device Token：
// iOS 10 及以后，注册获得device Token
[application registerForRemoteNotifications]; -
iOS 8-10，在 application:didRegisterUserNotificationSettings: 回调中向 APNs 推送服务注册，以获取 device Token：
- (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings{
[application registerForRemoteNotifications];
}
设置 device token
用户设备向 APNs 注册推送服务后，可获得 NSData 类型的 device Token。
请在 application:didRegisterForRemoteNotificationsWithDeviceToken: 回调中将该 device token 通过 setDeviceTokenData 提供给融云。
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
[[RCIMClient sharedRCIMClient] setDeviceTokenData:deviceToken];
}
获取推送数据
如果 App 需要支持 iOS 版本 7+，可使用 didReceiveRemoteNotification:fetchCompletionHandler: 方法获取推送数据（userInfo）。
在 iOS 10 及更高版本上，您需要使用 UNUserNotificationCenterDelegate 的两个 delegate 方法来获取通知信息。
-
如果 App 在前台，可以使用 userNotificationCenter:willPresentNotification:withCompletionHandler:，获取推送数据（
userInfo）。 -
App 用户点击通知时可以使用 userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:，获取推送数据（
userInfo）。/// ios >= 10.0
#pragma mark - UNUserNotificationCenterDelegate
#if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler NS_AVAILABLE_IOS(10_0){
// userInfo为远程推送的内容
completionHandler();
}
#endif
如果点击通知栏的远程推送时，App 已经被系统冻结，可使用下面方式获取：
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 远程推送的内容
NSDictionary *remoteNotificationUserInfo = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];
...
return YES;
}
App 可以通过 getPushExtraFromLaunchOptions 或 getPushExtraFromRemoteNotification 获取远程推送数据。
融云消息的远程推送内容格式如下：
{
"aps" :
{
"alert" : "You got your emails.",
"badge" : 1,
"sound" : "default"
},
"rc":{
"cType":"PR",
"fId":"2121",
"oName":"RC:TxtMsg",
"tId":"3232",
"rId":"3243",
"id":"5FSClm2gQ9V9BZ-kUZn58B",
"rc-dlt-identifier":"2FSClm2gQ9Q9BZ-kUZn54B"
},
"appData":"xxxx"
}
| 参数 | 类型 | 说明 |
|---|---|---|
| alert | String | 远程推送显示的内容。自带的消息会有默认显示，如果您使用的是自定义消息，需要在发送时设置。对应于 iOS 发送消息接口中的 pushContent。 |
| cType | String | 会话类型。PR（单聊）、DS（讨论组）、GRP（群组）、 CS（客服）、SYS（系统会话）、 MC（应用内公众服务） 、MP（跨应用公众服务）、PH（不落地通知）、UG（超级群）。 |
| bId | String | 超级群的频道 ID。仅超级群消息的远程推送内容会携带该字段。如果消息不属于任何频道，则 bId 字段为空字符串。 |
| fId | String | 消息发送者的用户 ID。 |
| oName | String | 消息类型。融云内置消息类型（详见内置消息类型 中的 ObjectName）或自定义的消息类型。 |
| tId | String | 为 Target ID。 |
| rId | String | 为接收者的用户 ID。 |
| id | String | 当前推送的消息唯一标识，对应消息路由功能中的 msgUID。 |
| rc-dlt-identifier | String | 当发送的是一条撤回消息推送时，为需要撤回消息的 ID，对应消息路由功能中的 msgUID。 |
| appData | String | 远程推送的附加信息，对应于 iOS 发送消息接口中的 pushData。 |
自定义推送通知
- 如需自定义远程推送内容，可在发送消息时提供 pushContent 内容。如果使用 IMKit UI 发送消息，可通过 WillSendMessage 回调中拦截并进行设置。
- 如需拦截并修改远程推送内容，App 需要自行创建
Notification Service Extension。详见 Apple 官方开发者文档 Modifying Content in Newly Delivered Notifications。 - 如需自定义远程推送通知显示样式，App 需要自行创建
Notification Content Extension。详见 Apple 官方开发者文档 Customizing the Appearance of Notifications
测试 APNs 远程推送
完成 APNs 推送集成后，您可以参照测试 APNs 远程推送进行测试。