集成 APNs 远程推送

融云服务端已集成 APNs 服务端功能。当 App 被杀进程、在后台被系统挂起或者在后台存活超过 2 分钟，IMLib 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：

1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后点按左上方的添加按钮 (+)。

   

2. 从选项列表中选择 App IDs（App ID），点按 Continue（继续）。

3. 从选项中，确认已自动选择了 App ID 类型，然后点按 Continue（继续）。

4. 在 Description（描述）栏位中输入 App ID 的名称或描述。请选择 Explicit App ID （精确 App ID），并在 Bundle ID 栏位中输入 App 的 Bundle ID。

   您在这里输入的精确 App ID 应该与 Xcode 中目标的 Summary （摘要）面板中输入的 Bundle ID 一致。

   

5. Capabilities （功能）下面会显示您的 App 类型和可以使用的功能。选中相应的复选框，以启用您想要使用的 App 功能。

   请勾选 Push Notifications 以启用推送通知功能。

   

6. 点按 Continue（继续），检查注册信息，然后点按 Register（注册）。

关于上述创建 App ID 步骤的详细说明，可参考 Apple 开发者帐户帮助文档：注册 App ID。

---

启用 App ID 的推送功能

提示

以下内容来自 Apple 开发者账户帮助文档： 启用推送通知。

以下步骤描述如何从 Apple 开发者账户为已有的 App ID 启用推送通知功能。如已启用，可跳过该步骤。

1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后找到对应的 App ID 进行配置。

2. 在 Capabilities 中勾选 Push Notifications。

   

启用 App ID 的推送功能后，请根据需要选择创建 P8 证书或者 P12 证书。

---

使用验证令牌（P8）

提示

如需了解 “使用验证令牌与 APNs 通信”，可参见 Apple 开发者文档 Establishing a Token-Based Connection to APNs。以下步骤来自 Apple 开发者账户帮助文档： 创建并下载启用了 APNs 的私钥。

您需要从 Apple 开发人员账户中创建并下载用于 APNs 推送服务的私钥（.p8 后缀的文本文件，也称为 “P8 证书”）。

1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Keys (密钥)，再点按左上方的添加按钮 (+)。

   

2. 在 Key Name（密钥名称）下面，为密钥输入唯一的名称。勾选 Apple Push Notifications service (APNs)，以启用 APNs 服务，再点按 Continue（继续）。

   

3. 检查密钥配置，再点击 Confirm。

4. 点按 Download（下载），立即生成并下载密钥文件。密钥会以文件扩展名为 .p8 的文本文件形式下载到本地。

   • 注意：请记录下 Key ID，后续需要使用。
   • 警告：密钥只可下载一次，下载后将从您的开发者帐户中移除，因此请务必妥善保管。如果 Download（下载）按钮处于停用状态，则表示您已经下载过这个密钥。

5. 点按 Done（完成）。

获取 .p8 文件后，您可以前往融云控制台上传文件。详见上传证书到融云。

---

使用 TSL 证书（P12）

提示

如需了解 p12 证书及“使用 TLS 证书与 APNs 通信”，可参见 Apple 开发者文档 Establishing a Certificate-Based Connection to APNs。

创建 p12 证书需要先从本地创建证书签名请求 (CSR)，再前往 Apple 开发者账户 上传 CSR 生成证书（.cer）文件，下载到本地，在 Mac 上导出为 .p12 格式的证书。

创建证书签名请求

Mac 上的“钥匙串访问”让您可以创建证书签名请求 (CSR)。

1. 打开 Mac 应用中的钥匙串访问，选择证书助理，再选择从证书颁发机构请求证书。

   

2. 填写证书信息，并保存到磁盘。

   • 在证书助理对话框中，在“用户电子邮件地址”栏位中输入电子邮件地址。
   • 在常用名称栏位中，输入密钥的名称 (例如，RongCloud)。
   • 将 CA 电子邮件地址栏位留空。
   • 选取存储到磁盘，然后点按继续。

   

---

生成 cer 格式证书

提示

如有多个 App，则需要为每个 App 生成单独的客户端 TLS 证书。

本步骤描述如何从 Apple 开发者账户生成 .cer 后缀的推送证书。注意，本步骤创建的 .cer 文件必须转换为 .p12 后缀的文件后才能在融云控制台上传使用。

以下两种方式仅存在 UI 操作上的区别，任选一种即可。

• 方式一：从 Apple 开发账户的 Certificates（证书）页面操作，生成 .cer 文件。

  1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Certificates (证书)，然后点按左上方的添加按钮 (+)。

     

  2. 选择证书种类，点按 Continue（继续）。

     • Apple Push Notification service SSL（Sandbox）：仅可向 APNs Sandbox 环境推送。仅可在融云控制台的环境使用此类证书，生产环境不允许使用此类证书。
     • Apple Push Notification service SSL（Sandbox & Production）：可向 APNs Sandbox 和 Production 环境推送，可在融云应用的开发环境和生产环境中使用。

     

  3. 选择需要生成证书的 App ID，点按 Continue（继续）。

     

  4. 在 Mac 上创建证书签名请求。如果您已按上文指导创建了 CSR 文件，可跳过这一步。

  5. 点击 Choose File（选取文件），将生成的请求证书（CSR文件）上传，点按 Continue（继续）。

     

  6. 点击 Download 将证书下载到本地。

• 方式二：从 Apple 开发账户的 Identifiers (标识符)页面操作，生成 .cer 文件。

  提示

  以下步骤来自 Apple 开发者账户帮助文档： 生成 APNs 客户端 TLS 证书。

  1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Identifiers (标识符)，然后选择要设置的 App ID。

  2. 在 Capabilities（功能）下，确认已选中 Push Notifications （推送通知）复选框。

  3. 点按 Configure（配置），进入创建证书页面。选择需要配置证书的环境，点按 Create Certificate（创建证书）。APNs 提供生产与开发两个环境。

     • Development SSL Certificate：仅可向 APNs Sandbox 环境推送。仅可在融云控制台的环境使用此类证书，生产环境不允许使用此类证书。
     • Production SSL Certificate：可向 APNs Sandbox 和 Production 环境推送，可在融云应用的开发环境和生产环境中使用。

     

  4. 在 Mac 上创建证书签名请求。如果您已按上文指导创建了 CSR 文件，可跳过这一步。

  5. 点击 Choose File（选取文件），将生成的请求证书（CSR文件）上传，点按 Continue（继续）。

     

  6. 点击 Download 将证书下载到本地。

---

转换 cer 文件为 P12 格式证书

1. 双击下载到本地的证书文件（.cer），证书会自动导入钥匙串中。证书的名称为 Apple [Development/Production] iOS Push Services: [Bundle ID]，或者 Apple Push Services: [Bundle ID]。

2. 在 Mac 应用 钥匙串访问 中，左侧点击 登陆 和 证书，选择刚导入的证书，右键导出为扩展名为 .p12 的证书文件。

   

3. 系统将显示一个对话框，提示输入将用于保护导出项目的密码。您在此输入的密码将在后续将 p12 证书上传到融云后台时使用，请务必记录该密码。

4. 再输入一次证书密码，执行导出操作。

---

在融云控制台配置 APNs 推送

您需要将创建的 APNs Auth Key 文件（P8）或者 TSL 证书（P12）上传到融云后台，融云服务端才能与 APNs 通信，向 iOS 客户端发送推送通知。

提示

验证推送的 ipa 包的打包方式需要与融云对应 AppKey 配置的证书环境匹配：

• 开发环境 AppKey 上传开发环境的 p12 推送证书或者 p8 证书，需要打 development 的 ipa 应用或者 XCode 直接运行。
• 生产环境 AppKey 上传生产环境的 p12 推送证书或者 p8 证书，需要打 adhoc 的 release 包进行推送测试。

1. 前往 融云控制台，点击 应用标识 并找到当前需要集成的项目，然后点击 IM 服务>应用标识及推送设置>设置推送。如果未创建可点击 添加。

   

2. 填写 Bundle Identifier。

3. 如果您创建了 P8 证书文件，鉴权方式请选择 Token Authentication。具体步骤如下：

   1. 点击上传 P8 文件，选择您创建的 APNs 签名密钥 .p8 文件。

      

   2. 填写 Key ID（参见创建 p8 证书）。

   3. 填写 Team ID。您可以在 Apple 开发者账户 的 Membership 页面获取 Team ID。

      

4. 如果您创建了 P12 证书文件，请注意融云应用的生产环境仅接受 APNs 通用证书（Sandbox & Production）。请根据证书类型和当前环境选择合适的鉴权方式：

   1. 如果上传 APNs 开发证书（Sandbox），请选择 P12 证书。
   2. 如果上传 APNs 通用证书（Sandbox & Production），请选择 P12 通用证书。
   3. 上传证书，填写证书密码。
   4. 如果在融云应用的开发环境中使用 APNs 通用证书（Sandbox & Production），请在推送环境中向 APNs 的 Sandbox 或 Production 环境推送。在生产环境使用 APNs 通用证书时，仅支持推送到 APNs 的 Production 环境，无需选择。

---

创建 Provisioning Profile 文件

您需要创建一个 Provisioning Profile（配置文件），才能在设备上运行您的应用程序，使用推送通知功能。您需要从 Apple 开发者账户创建并下载预置描述文件，然后在 Xcode 中安装预置描述文件。

1. 在 Certificates, Identifiers & Profiles（证书、标识符和描述文件）中，点按边栏中的 Profiles (标识符)，然后点按左上方的添加按钮 (+)。

   

2. 选择 Provisioning Profile 的环境后点按 Continue

   

3. 选择要创建 Provisioning Profile 的 App ID 后，点按 Continue。

   

4. 选择所属的开发者证书, 如果创建了多个，选择 Select All，点按 Continue。

   

5. 为该 Provisioning Profile 选择将要安装的设备（一般选择 Select All），点按 Continue。

   

6. 填写 Profile Name。建议命名为环境 + AppID，点击 generate 完成创建。

   

7. 创建成功后，点击 Download 下载到本地。

8. 双击下载的 Provisioning Profile 文件，添加到 Xcode。

客户端配置

请求推送权限

无论是本地推送还是远程推送，都需要申请权限。

Objective C

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

  Objective C

  // iOS 10 及以后，注册获得device Token
  [application registerForRemoteNotifications];

• iOS 8-10，在 application:didRegisterUserNotificationSettings: 回调中向 APNs 推送服务注册，以获取 device Token：

  Objective C

  - (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings{
      [application registerForRemoteNotifications];
  }

---

设置 device token

用户设备向 APNs 注册推送服务后，可获得 NSData 类型的 device Token。

请在 application:didRegisterForRemoteNotificationsWithDeviceToken: 回调中将该 device token 通过 setDeviceTokenData 提供给融云。

Objective C

- (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）。

  Objective C

  /// 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 已经被系统冻结，可使用下面方式获取：

Objective C

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 远程推送的内容
    NSDictionary *remoteNotificationUserInfo = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];

    ...

    return YES;
}

App 可以通过 getPushExtraFromLaunchOptions 或 getPushExtraFromRemoteNotification 获取远程推送数据。

融云消息的远程推送内容格式如下：

JSON

{
　　"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 远程推送进行测试。