实时音视频 iOS 离线推送接入（中国大陆）

说明：
本文档适用于在 中国大陆 App Store 上架的 App。如果您的 App 面向海外市场，请参见 iOS 通话离线推送接入（海外场景）。
TUICallKit 组件支持在 App 退到后台或被系统杀死时，通过离线推送唤醒被叫用户，使其能及时收到来电。本文档为您提供两种集成方式：基础推送（免费）和 使用 付费推送（付费），您可以根据自己的业务需求选择。
集成效果
按照本文档接入后，您的 App 将拥有完整的通话离线唤醒能力：
LCK 系统全屏接听界面（iOS 17.4+）：进程被杀或锁屏状态下，拥有微信同款的原生通话能力，无差别唤醒系统级全屏接听界面
APNs 通知横幅（全系统）：弹出通知栏横幅提示用户来电，点击拉起 App 进入通话页面
LCK 接听前效果
LCK 接听后效果
APNs 锁屏时效果
APNs 在后台时效果
﻿
﻿
﻿
﻿
方案选择
您的需求
接入方案
费用
仅在 App 前台使用通话，不需要离线唤醒。
无需接入推送，跳过本文档
免费
仅需要 App 退后台/被杀死时收到来电响铃，无其他诉求。
﻿方案一：基础推送﻿
免费
需要数据统计、链路追踪、营销推送、跨平台支持等更完整的能力。
﻿方案二：付费推送﻿
付费， 需要 开通 TIMPush 服务。
说明：
离线推送能力需要在 iOS 17.4 及以上系统中使用，低版本系统将通过 APNs 通知横幅唤醒。
VoIP Push 无法复用 APNs 普通推送证书，需要单独在苹果开发者网站上 申请 VoIP Push 证书。
禁止：
中国大陆 App Store 对 Apple CallKit 使用存在隐性限制，可能导致 App 上架审核被驳回！
本文方案使用 LCK（LiveCommunicationKit）系统弹窗 + APNs 通知横幅作为离线唤醒方式，不引入 Apple CallKit，请勿在 Podfile 中使用 pod 'AtomicXCore/WithAppleCallKit' 或类似启用 CallKit 的子库。如需启用 Apple CallKit，请参见 iOS 通话离线推送接入（海外场景） 文档。
完成选择后，请先阅读 前置准备 章节完成工程配置和证书申请，再前往对应方案章节完成接入。
前置准备
无论选择哪种方案，都需要先完成工程配置、证书申请和证书上传。
步骤 1. 完成工程配置
1. 如下图，确认您工程的 Capability 中是否添加 Push Notifications 能力。
﻿
2. 如下图，请检查您工程 Capability 的 Background Modes 中，是否开启了 Voice over IP 选项。
﻿
步骤 2. 申请离线推送证书
iOS 通话离线推送需要 两种证书：
VoIP Push 证书：用于唤起来电界面（iOS 17.4+ 的 LCK 能力，核心）
APNs 证书：用于在低版本系统下展示通知栏横幅（兜底）
两种证书都需要申请。下面分三步：先做通用准备，再分别申请 VoIP 和 APNs。
步骤 2.1 通用准备
步骤 2.1.1 开启 AppID 的 Push Notifications 能力
1. 登录 苹果开发者中心 网站，单击 Certificates, IDs & Profiles 选项卡中的 Identifiers，进入 Certificates, Identifiers & Profiles 页面。
﻿
﻿
﻿
2. 单击 Identifiers 右侧的 “+”。 
﻿
﻿
﻿
3. 您可以参考如下步骤新建一个 AppID，或者在您原有的 AppID 上增加 Push Notifications 的 Service。
说明：
需要注意的是，您 App 的 Bundle ID 不能使用通配符 *，否则将无法使用远程推送服务。
4. 勾选 App IDs，单击 Continue 进行下一步。
5. 选择 App，单击 Continue 进行下一步。
6. 配置 BundleID 等其他信息，单击 Continue 进行下一步。
7. 勾选 Push Notifications，开启远程推送服务。
﻿
﻿
﻿
步骤 2.1.2 制作 CSR 文件
后续申请 VoIP 和 APNs 证书都需要上传 CSR 文件（同一份可复用）
1. 在 Mac 上打开钥匙串访问工具（Keychain Access），在菜单中选择钥匙串访问 > 证书助理 > 从证书颁发机构请求证书（Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority）。
﻿
﻿
﻿
2. 输入用户电子邮件地址（您的邮箱）、常用名称（您的名称或公司名），选择 “存储到磁盘（Saved to disk）”，单击继续，系统将生成一个 *.certSigningRequest 文件，保存备用。
步骤 2.2 申请 VoIP Push 证书
1. 进入 Certificates, IDs & Profiles > Certificates。
﻿
﻿
﻿
2. 单击 Certificates 右侧的 +。
﻿
﻿
﻿
3. 在 Create a New Certificate 中选择 VoIP Services Certificate，单击 Continue。
4. 选择您的 App 的 Bundle ID，单击 Continue。
5. 在 CSR 上传页面，单击 Choose File 上传 2.1 节 中生成的 *.certSigningRequest 文件。
﻿
﻿
﻿
6. 单击 Continue 生成证书，单击 Download 下载 voip_services.cer 到本地。
7. 双击 .cer 文件导入钥匙串，然后在登录 > 我的证书中找到 VoIP Services 证书，右键导出为 .p12 文件。
说明：
保存 .p12 文件时必须设置密码，否则收不到推送。
VoIP Push 证书不区分开发环境和生产环境，只需申请一份。
步骤 2.3 申请 APNs 证书
1. 进入 Certificates, IDs & Profiles > Identifiers，选择您的 AppID，找到 Push Notifications 配置项，单击 Configure。
﻿
﻿
﻿
2. 在 Apple Push Notification service SSL Certificates 窗口中，您会看到两个入口：Development 和 Production，分别用于开发环境和生产环境。
3. 先选择 Development > Create Certificate，在 CSR 上传页面单击 Choose File 上传 2.1 节 中生成的 *.certSigningRequest 文件。
﻿
﻿
﻿
4. 单击 Continue 生成证书，单击 Download 下载开发环境的 .cer 文件到本地。
5. 重复上述步骤 3-4，这次选择 Production，生成并下载生产环境的 .cer 文件。
6. 分别双击下载的两个 .cer 文件导入钥匙串，然后在登录 > 我的证书中分别右键导出：
开发环境（Apple Development iOS Push Service）> .p12
生产环境（Apple Push Services）> .p12
注意：
保存 .p12 文件时必须设置密码，否则收不到推送。
APNs 证书需要分别申请开发环境和生产环境两份。
生产环境证书实际是 Sandbox + Production 的合并证书，可同时用于开发和生产，但仍建议按环境分别上传到 IM 控制台。
步骤 3. 上传证书到 IM 控制台
﻿打开 IM 控制台，选择您创建的 IM 应用，并按照如下步骤 APNs 证书和 VoIP 证书：
1. 选择您的 IM 应用，进入应用的基础配置页面，在离线推送证书配置选项卡中，单击立即前往。
﻿
﻿
﻿
2. 在厂商配置中，切换到 iOS, 点击添加证书按钮，然后在悬浮页面中选择证书类型，分别上传 APNs 证书（p12）和 VoIP 证书（p12），设置证书密码后单击确认。
﻿
﻿
﻿
说明：
添加证书时，推送类型默认为 APNs，不影响 VoIP 证书的上传和使用。
VoIP Push 证书本身不区分生产环境和测试环境，生产环境和开发环境使用的是同一份 VoIP Push 证书，请分别上传。
上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
上传证书需要设置密码，无密码收不到推送。
发布 App Store 的证书需要设置为生产环境，否则无法收到推送。
上传的 p12 证书必须是自己申请的真实有效的证书。
3. 上传完成后，记录 APNs 和 VoIP 不同环境下的证书 ID。
﻿
﻿
﻿
说明：
开发环境和生产环境下的证书 ID 要严格区分，请根据实际环境填写。
方案一：基础推送
步骤 1. 添加 Pod 依赖
在您的 Podfile 文件中添加以下依赖：
pod 'AtomicXCore'
执行以下命令安装组件：
pod install
注意：
本方案默认使用 LCK + APNs 实现来电唤醒，请勿使用 pod 'AtomicXCore/WithAppleCallKit'，该子库会引入 Apple CallKit，存在中国大陆 App Store 审核风险。
步骤 2. 上报证书 ID
在 App 启动时，调用 LoginStore.setCertificateID 上报 前置准备 中获取的证书 ID。
import AtomicXCore
﻿
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
﻿
    // 上报 APNs 证书 ID 和 VoIP 证书 ID
    LoginStore.shared.setCertificateID(
        apnsCertificateID: 1234,
        voipCertificateID: 5678
    )
﻿
    return true
}
说明：
当两个证书 ID 都填写时，AtomicXCore 会自动启用「VoIP 优先 + APNs 兜底」的双通道策略：iOS 17.4+ 设备通过 LCK 唤起系统级来电界面；如果设备不支持 VoIP 或 LCK（例如低版本系统、关闭了 VoIP 后台权限），SDK 会自动通过 APNs 通知横幅展示来电提醒，最大程度保证触达。这是本方案相对推送插件的独有优势。
仅需要 APNs 横幅、不需要 VoIP 来电的客户，可只填 apnsCertificateID，将 voipCertificateID 传 0。
仅需要 VoIP 来电、不需要 APNs 横幅的客户，可只填 voipCertificateID，将 apnsCertificateID 传 0。
步骤 3. 拨打 VoIP 通话
AtomicXCore 的 CallStore 已经默认使用 VoIP 推送，CallStore 内部会自动配置以下推送信息，默认推送内容如下：
字段
默认值
推送类型
VoIP
推送标题
主叫用户的 ID
推送描述
中文环境下为「您有新的来电」，其它语言为「You have a new call」
iOS 铃声
phone_ringing.mp3
如果您想自定义推送标题或描述，可在发起通话时通过 CallParams 传入 offlinePushTitle / offlinePushDescription，传入后会覆盖上述默认值。
import AtomicXCore
﻿
// 构造通话参数
var params = CallParams()
params.timeout = 30                              // 超时时间（秒）
params.userData = "自定义数据"                     // 扩展信息（可选）
﻿
// 可选：自定义离线推送标题和描述（不填则使用默认值）
params.offlinePushTitle = "张三"                  // 覆盖默认标题
params.offlinePushDescription = "邀请您视频通话"    // 覆盖默认描述
﻿
// 发起通话
let userIdList = ["被叫用户的 userID"]
let mediaType = CallMediaType.video    // .video 视频通话，.audio 语音通话
﻿
CallStore.shared.calls(
    participantIds: userIdList,
    mediaType: mediaType,
    params: params
) { result in
    switch result {
    case .success:
        // 通话发起成功，此时可以跳转到您自己的通话页面
        break﻿
    case .failure(let error):
        // 通话失败处理
        break
    }
}
方案二：付费推送
步骤 1. 开通服务
进入 IM 控制台 > 插件市场，单击立即购买或免费试用。 
﻿
注意：
购买及免费试用规则详见 计费说明。
步骤 2. 接入 TUIVoIPExtension 组件
使用 CocoaPods 导入组件，具体步骤如下：
1. 在您的 Podfile 文件中添加以下依赖。
pod 'TUIVoIPExtension/CallKit'
2. 执行以下命令，安装组件。
pod update
3. 上报 控制台的证书 ID。
Swift
Objective-C
import TUIVoIPExtension
﻿
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // 上报【前置准备】中获取的 VoIP 证书 ID。
    TUIVoIPExtension.setCertificateID(1234)
    
    return true
}
#import <TUIVoIPExtension/TUIVoIPExtension.h>
﻿
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // 上报证书 ID
    [TUICallKitVoIPExtension setCertificateID:1234];
    
    return YES;
}
步骤 3. 拨打 VoIP 通话
调用方式与方案一一致，请参考 方案一 > 拨打 VoIP 通话 章节。
常见问题
获取不到 VoIP Push，如何处理？
1. 首先检查下 App 的运行环境和证书的环境是否一致，证书 ID 是否匹配，如果不一致，无法收到推送。
2. 请确认当前您登录的账号是否处于离线状态：按 home 键切后台、登录后主动杀进程退出。VoIP Push 目前只支持离线状态下的推送。
3. 检查 前置准备  是否正确。
4. 尝试重启测试手机来清除系统缓存和内存（很重要）。
如何自集成 VoIP 推送功能？
我们也支持您自己通过 SDK 的方式来集成 VoIP 推送的能力，整体的方案设计如下：
﻿
相关流程说明：
1. 参考 前置准备 申请 VoIP 推送证书，并在 IM 控制台上传证书获取证书 ID。
2. 参考 Apple PushKit 使用获取设备 token。
3. 使用 IMSDK 的 setVOIP 接口向 IM 服务器上报设备 token。
4. 参考 Apple LiveCommunicationKit 使用展示推送弹窗。
5. 参考 TUICallKit 接口的使用 发起 VoIP 通话。
LCK 接听前效果	LCK 接听后效果	APNs 锁屏时效果	APNs 在后台时效果
您的需求	接入方案	费用
仅在 App 前台使用通话，不需要离线唤醒。	无需接入推送，跳过本文档	免费
仅需要 App 退后台/被杀死时收到来电响铃，无其他诉求。	方案一：基础推送	免费
需要数据统计、链路追踪、营销推送、跨平台支持等更完整的能力。	方案二：付费推送	付费，需要开通 TIMPush 服务。
字段	默认值
推送类型	VoIP
推送标题	主叫用户的 ID
推送描述	中文环境下为「您有新的来电」，其它语言为「You have a new call」
iOS 铃声	`phone_ringing.mp3`
iOS 离线推送接入（中国大陆）

本页目录：

集成效果

方案选择

前置准备

步骤 1. 完成工程配置

步骤 2. 申请离线推送证书

步骤 2.1 通用准备

步骤 2.1.1 开启 AppID 的 Push Notifications 能力

步骤 2.1.2 制作 CSR 文件

步骤 2.2 申请 VoIP Push 证书

步骤 2.3 申请 APNs 证书

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

方案一：基础推送

步骤 1. 添加 Pod 依赖

步骤 2. 上报证书 ID

步骤 3. 拨打 VoIP 通话

方案二：付费推送

步骤 1. 开通服务

步骤 2. 接入 TUIVoIPExtension 组件

步骤 3. 拨打 VoIP 通话

常见问题

获取不到 VoIP Push，如何处理？

如何自集成 VoIP 推送功能？
