实时音视频
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 实时音视频 > 视频通话（含 UI） > 离线唤醒（TUICallKit） > iOS > APNs

APNs

最近更新时间：2023-05-09 09:36:35

我的收藏

本页目录：

离线唤醒功能，能够让您的 App 在后台运行或者离线状态下依然能够收到音视频通话的响铃呼叫，TUICallKit 使用 Apple 提供的系统级推送通道（APNs）来进行消息通知。

配置离线推送

1. 开启 App 远程推送。
2. 生成证书。
3. 上传证书到 IM 控制台。
4. 完成工程配置
5. 在 App 每次登录时，向苹果获取 deviceToken。
6. 调用 setAPNS 接口将其上报到 IM 后台。

步骤1. 开启 App 远程推送

1. 登录 苹果开发者中心 网站，单击 ”Certificates,Identifiers & Profiles” 或者侧栏的 ”Certificates, IDs & Profiles”，进入 Certificates, IDs & Profiles 页面。



2. 单击 Identifiers 右侧的“+“。




3. 您可以参考如下步骤新建一个 AppID，或者在您原有的 AppID 上增加 Push Notification 的 Service。
说明：
需要注意的是，您 App 的 Bundle ID 不能使用通配符 *，否则将无法使用远程推送服务。
4. 勾选 “App IDs”，单击 ”Continue” 进行下一步。



5. 选择 “App”，单击 ”Continue“ 进行下一步。



6. 配置Bundle ID等其他信息，单击 “Continue“ 进行下一步。



7. 勾选 “Push Notifications”，开启远程推送服务。




步骤2：生成证书

1. 选中您的 AppID，选择 “Configure“。



2. 可以看到在 “Apple Push Notification service SSL Certificates” 窗口中有两个 SSL Certificate ，分别用于开发环境（Development）和生产环境（Production）的远程推送证书，如下图所示：



3. 我们先选择开发环境（Development）的 “Create Certificate”，系统将提示我们需要一个Certificate Signing Request（CSR）。



4. 在 Mac 上打开钥匙串访问工具（Keychain Access），在菜单中选择 ”钥匙串访问” > “证书助理“ > “从证书颁发机构请求证书“（Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority）。



5. 输入用户电子邮件地址（您的邮箱）、常用名称（您的名称或公司名），选择 “存储到磁盘（Saved to disk）”，单击继续，系统将生成一个 *.certSigningRequest 文件。



6. 返回上述 第3步 中 Apple Developer 网站刚才的页面，单击 ”Choose File“ 上传生成的*.certSigningRequest文件。



7. 单击 ”Continue“，即可生成推送证书。



8. 单击 “Download“ 下载开发环境的 Development SSL Certificate 到本地。



9. 再次按照上述步骤1 - 8，将生产环境的 Production SSL Certificate 下载到本地。
说明：
生产环境的证书实际是开发(Sandbox)+生产(Production)的合并证书，可以同时作为开发环境和生产环境的证书使用。






10. 双击打开下载的开发环境和生产环境的 SSL Certificate，系统会将其导入钥匙串中。
11. 打开钥匙串应用，在“登录“ > “我的证书”，右键分别导出刚创建的开发环境（Apple Development IOS Push Service）和生产环境（Apple Push Services）的 P12 文件。
说明：
保存P12文件时，请务必要为其设置密码。

步骤3：上传证书到 IM 控制台

1. 登录 即时通信 IM 控制台。
2. 单击目标应用卡片，进入应用的基础配置页面。



3. 单击 “iOS 原生离线推送设置“ 右侧的 “添加证书”。
4. 选择证书类型，上传 iOS 证书（p.12），设置证书密码，单击【确认】。



说明：
上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
上传证书需要设置密码，无密码收不到推送。
发布 App Store 的证书需要设置为生产环境，否则无法收到推送。
上传的 p12 证书必须是自己申请的真实有效的证书。
5. 待推送证书信息生成后，记录证书的 ID。




步骤4：完成工程配置

要在应用程序中添加所需的权限，请在 Xcode 项目中启用推送通知功能。
打开 Xcode 项目，在 Project > Target > Capabilities 页面中点击红框中的加号按钮，然后选择并添加 Push Notifications，添加后的结果如图中黄框所示：




步骤5：在 App 每次登录时，向苹果获取 deviceToken

您可以在您的 App 中添加如下代码，用来向苹果的后台服务器获取 deviceToken：
说明：
考虑到合规，建议您在用户同意隐私协议之后再向苹果请求 deviceToken。
// 向苹果后台请求 DeviceToken
- (void)registerNotification {
    [[UIApplication sharedApplication] registerUserNotificationSettings:
              [UIUserNotificationSettings settingsForTypes:
              (UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge)
              categories:nil]];
    [[UIApplication sharedApplication] registerForRemoteNotifications];
}

// 在 AppDelegate 的回调中会返回 deviceToken，需要在登录后上报给腾讯云后台
-(void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    // 记录下 Apple 返回的 deviceToken
    _deviceToken = deviceToken;
}

步骤6：调用 接口将其上报到 IM 后台

在 IM SDK 登录成功后，就可以调用 setAPNS 接口，将 步骤5 中获取的 deviceToken 上传到腾讯云后台，示例代码如下:
- (void)pushRegisterIfLogined {
  if (self.deviceToken) {
      V2TIMAPNSConfig *config = [[V2TIMAPNSConfig alloc] init];
      // 用户自己到苹果注册开发者证书，在开发者帐号中下载并生成证书(p12 文件)，将生成的 p12 文件传到腾讯证书管理控制台，
      // 控制台会自动生成一个证书 ID，将证书 ID 传入以下 businessID 参数中。
      config.businessID = sdkBusiId;
      // 苹果后台服务器获取的 deviceToken
      config.token = self.deviceToken;
      [[V2TIMManager sharedInstance] setAPNS:config succ:^{
           NSLog(@"%s, succ", __func__");
      } fail:^(int code, NSString *msg) {
           NSLog(@"%s, fail, %d, %@", __func__, code, msg);
      }];
  }
  // ...
}

自定义离线铃声

请在调用 call 拨打电话的时候设置 params 的 offlinePushInfo 中的 iOSSound 字段， iOSSound 传语音文件名。
注意：
离线推送声音设置（仅对 iOS 生效），如果要自定义 iOSSound，需要先把语音文件链接进 Xcode 工程，然后把语音文件名（带后缀名）设置给 iOSSound。
铃声时长应小于30s。
Objective-C
Swift

[[TUICallKit createInstance] call:@"mike 的 id" params:[self getCallParams] callMediaType:TUICallMediaTypeVideo];

- (TUICallParams *)getCallParams {
    TUIOfflinePushInfo *offlinePushInfo = [self createOfflinePushInfo];
    TUICallParams *callParams = [TUICallParams new];
    callParams.offlinePushInfo = offlinePushInfo;
    callParams.timeout = 30;
    return callParams;
}

+ (TUIOfflinePushInfo *)createOfflinePushInfo {
    TUIOfflinePushInfo *pushInfo = [TUIOfflinePushInfo new];
    pushInfo.title = @"";
    pushInfo.desc = TUICallingLocalize(@"TUICallKit.have.new.invitation");
    pushInfo.iOSPushType = TUICallIOSOfflinePushTypeAPNs;
    pushInfo.ignoreIOSBadge = NO;
    pushInfo.iOSSound = @"phone_ringing.mp3";
    pushInfo.AndroidSound = @"phone_ringing";
    // OPPO必须设置ChannelID才可以收到推送消息，这个channelID需要和控制台一致
    // OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.
    pushInfo.AndroidOPPOChannelID = @"tuikit";
    // FCM channel ID, you need change PrivateConstants.java and set "fcmPushChannelId"
    pushInfo.AndroidFCMChannelID = @"fcm_push_channel";
    // VIVO message type: 0-push message, 1-System message(have a higher delivery rate)
    pushInfo.AndroidVIVOClassification = 1;
    // HuaWei message type: https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835
    pushInfo.AndroidHuaWeiCategory = @"IM";
    return pushInfo;
}
let params = TUICallParams()
let pushInfo: TUIOfflinePushInfo = TUIOfflinePushInfo()
pushInfo.title = "TUICallKit"
pushInfo.desc = "TUICallKit.have.new.invitation"
pushInfo.iOSPushType = .apns
pushInfo.ignoreIOSBadge = false
pushInfo.iOSSound = "phone_ringing.mp3"
pushInfo.androidSound = "phone_ringing"
// OPPO必须设置ChannelID才可以收到推送消息，这个channelID需要和控制台一致
// OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.
pushInfo.androidOPPOChannelID = "tuikit"
// FCM channel ID, you need change PrivateConstants.java and set "fcmPushChannelId"
pushInfo.androidFCMChannelID = "fcm_push_channel"
// VIVO message type: 0-push message, 1-System message(have a higher delivery rate)
pushInfo.androidVIVOClassification = 1
// HuaWei message type: https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835
pushInfo.androidHuaWeiCategory = "IM"
params.userData = "User Data"
params.timeout = 30
params.offlinePushInfo = pushInfo
TUICallKit.createInstance().call(userId: "123456", callMediaType: .audio, params: params) {

} fail: {
    code, message in 
}


常见问题

1、收不到推送，且后台报错 bad devicetoken？

Apple 的 deviceToken 与当前编译环境有关。如果 登录 IMSDK 后上传 deviceToken 到腾讯云 所使用的证书 ID 和 token 不一致，就会报错。
如果使用的是 Release 环境编译，则 - application:didRegisterForRemoteNotificationsWithDeviceToken: 回调返回的是发布环境的 token，此时 businessID 需要设置生产环境的 [证书 ID ](#businessid :缺少内容)。
如果使用的是 Debug 环境编译，则 - application:didRegisterForRemoteNotificationsWithDeviceToken: 回调返回的是开发环境的 token，此时 businessID 需要设置开发环境的证书 ID。
Objective-C
Swift
V2TIMAPNSConfig *config = [[V2TIMAPNSConfig alloc] init];
// 用户自己到苹果注册开发者证书，在开发者帐号中下载并生成证书(p12 文件)，将生成的 p12 文件传到腾讯证书管理控制台，
// 控制台会自动生成一个证书 ID，将证书 ID 传入以下 businessID 参数中。*/
config.businessID = sdkBusiId;
config.token = self.deviceToken;
[[V2TIMManager sharedInstance] setAPNS:config succ:^{

} fail:^(int code, NSString *msg) {

}];
let config = V2TIMAPNSConfig()
config.businessID = sdkBusiId
config.token = deviceToken
V2TIMManager.sharedInstance().setAPNS(config) {
       
} fail: { code, message in
   
}


2、iOS 开发环境下，注册偶现不返回 deviceToken 或提示 APNs 请求 token 失败？

此问题现象是由于 APNs 服务不稳定导致的，可尝试通过以下方式解决：
1. 给手机插入 SIM 卡后使用 4G 网络测试。
2. 卸载重装、重启 App、关机重启后测试。
3. 打生产环境的包测试。
4. 更换其它 iOS 系统的手机测试。
中国站