文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>视频通话 SDK>离线唤醒>iOS>iOS 离线推送接入（海外场景）

iOS 离线推送接入（海外场景）

最近更新时间：2026-06-15 17:06:44

我的收藏

本页目录：

说明：
本文档适用于在 海外 App Store 上架的 App。如果您的 App 面向中国大陆，请参见 iOS 通话离线推送接入（中国大陆）。
TUICallKit 组件支持在 App 退到后台或被系统杀死时，通过离线推送唤醒被叫用户，使其能及时收到来电。本文档为您提供两种集成方式：基础推送（免费）和使用付费推送（付费），您可以根据自己的业务需求选择。

集成效果

按照本文档接入后，您的 App 将在 iOS 14.0 及以上全版本通过 Apple CallKit 提供原生电话级别的全屏来电界面体验，进程被杀或锁屏状态下也能唤醒系统级来电界面。
锁屏时的效果
应用在后台的效果
应用在后台展开的效果




方案选择

您的需求
接入方案
费用
仅在 App 前台使用通话，不需要离线唤醒。
无需接入推送，跳过本文档
免费
仅需要 App 退后台/被杀死时收到来电响铃，无其他诉求。
免费
需要数据统计、链路追踪、营销推送、跨平台支持等更完整的能力。
付费， 需要 开通 TIMPush 服务。
说明：
本方案使用 Apple CallKit 唤起系统全屏来电界面，覆盖 iOS 14.0 及以上全版本。
VoIP Push 无法复用 APNs 普通推送证书，需要单独在苹果开发者网站上 申请 VoIP Push 证书。
注意：
中国大陆 App Store 对 Apple CallKit 使用存在隐性限制，可能导致 App 上架审核被驳回。如果您的 App 同时上架中国大陆 App Store，请参见 iOS 通话离线推送接入（中国大陆） 使用不含 CallKit 的方案。
完成选择后，请先阅读 前置准备 章节完成工程配置和证书申请，再前往对应方案章节完成接入。

前置准备

无论选择方案一还是方案二，都需要先完成工程配置、证书申请和证书上传。

步骤 1. 完成工程配置

1. 确认您工程的 Capability 中已添加 Push Notification 能力。



2. 检查您工程 Capability 的 Background Modes 中，是否同时开启了 Voice over IP 和 Remote notifications 选项。




步骤 2. 申请 VoIP Push 证书

海外通话场景的离线推送由 VoIP Push 证书 唤起 CallKit 全屏来电界面，您只需申请该证书即可。
说明：
如果您的 App 还有非通话类的离线消息推送需求（如 IM 文字消息），可另行申请 APNs 证书，开通 TIMPush 服务 并参考 IM 离线推送接入文档，本文档不再赘述。
下面分两步：先做通用准备（CSR + AppID 配置），再申请 VoIP Push 证书。

步骤 2.1 通用准备

步骤 2.1.1 开启 AppID 的 Push Notifications 能力
您可以在已有的 AppID 上增加 Push Notifications 服务，也可以新建一个 AppID。
说明：
您 App 的 Bundle ID 不能使用通配符 *，否则将无法使用远程推送服务。
1. 登录 苹果开发者中心，进入 Certificates, IDs & Profiles > Identifiers。



2. 如果您已有 AppID，直接选中后跳到步骤 6；如果需要新建 AppID，单击 Identifiers 右侧的 +。



3. 勾选 App IDs，单击 Continue 进行下一步。
4. 选择 App，单击 Continue 进行下一步。
5. 配置 Bundle ID 等其他信息，单击 Continue 进行下一步。
6. 在 Capabilities 列表中勾选 Push Notifications，单击 Save（或新建时单击 Continue > Register）。



步骤 2.1.2 制作 CSR 文件
申请 VoIP Push 证书时需要上传 CSR 文件，先准备好：
1. 在 Mac 上打开钥匙串访问（Keychain Access），菜单选择 钥匙串访问 → 证书助理 → 从证书颁发机构请求证书。



2. 输入您的邮箱地址和常用名称，选择存储到磁盘，单击继续。系统会生成一个 *.certSigningRequest 文件，保存到桌面备用。

步骤 2.2 申请 VoIP Push 证书

说明：
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 文件时必须设置密码，否则收不到推送。

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

打开 IM 控制台，选择您创建的 IM 应用，按如下步骤上传 VoIP 证书：
1. 进入应用的基础配置页面，在离线推送证书配置选项卡中，单击立即前往。



2. 在厂商配置中切换到 iOS，点击添加证书按钮，推送类型选择 VoIP，上传上一步导出的 .p12 文件，设置证书密码后单击确认。



说明：
VoIP Push 证书本身不区分生产环境和测试环境，但 IM 控制台需要为开发环境和生产环境分别添加，使用的都是同一份 .p12 文件。
上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
上传证书必须设置密码，否则收不到推送。
发布 App Store 的证书需要设置为生产环境，否则无法收到推送
3. 上传完成后，分别记录 VoIP 证书在开发环境和生产环境下的证书 ID。



说明：
开发环境和生产环境下的证书 ID 要严格区分，请根据实际环境填写。

方案一：基础推送

步骤 1. 添加 Pod 依赖

在您的 Podfile 文件中添加以下依赖：
pod 'AtomicXCore/WithAppleCallKit'
执行以下命令安装组件：
pod install
该 Pod 在 AtomicXCore 默认能力的基础上额外集成 Apple CallKit，使 iOS 14.0 及以上全版本用户都能获得 CallKit 原生电话级别的全屏来电体验。
注意：
WithAppleCallKit 子库会引入 Apple CallKit，存在中国大陆 App Store 审核风险。如果您的 App 同时上架中国大陆 App Store，请参见 常见问题 > 我的 App 需要同时上架中国大陆和海外 App Store，应该接哪一个？

步骤 2. 上报证书 ID

在 App 启动时，调用 LoginStore.setCertificateID 上报 前置准备 中获取的 VoIP 证书 ID。
import AtomicXCore

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // 上报 VoIP 证书 ID
    LoginStore.shared.setCertificateID(voipCertificateID: 5678)

    return true
}
说明：
海外场景下 CallKit 已经覆盖 iOS 14.0+ 全版本，通话来电统一通过 VoIP + CallKit 唤起，纯通话 App 只需填写 VoIP 证书 ID 即可。

步骤 3. 拨打 VoIP 通话

AtomicXCore 的 CallStore 在发起通话时自动携带 VoIP 离线推送参数，您不需要手动设置任何 offlinePushInfo 字段。默认推送内容如下：
字段
默认值
推送类型
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
    }
}

方案二：付费推送

注意：
TUIVoIPExtension 是 TIMPush 的一个子模块，由于 VoIP 推送的特殊性，TUIVoIPExtension 是独立发布的。使用 TUIVoIPExtension 插件首先需要开通 TIMPush 服务。

步骤 1. 开通服务

进入 IM 控制台 > 插件市场，单击立即购买或免费试用（每个应用可免费试用一次，有效期 7 天）。



注意：
推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您业务正常使用，请提前 购买/续费。

步骤 2. 接入 TUIVoIPExtension 组件

使用 CocoaPods 导入组件，具体步骤如下：
1. 在您的 Podfile 文件中添加以下依赖：
pod 'TUIVoIPExtension/CallKit'
2. 执行以下命令，安装组件：
pod update

步骤 3. 上报证书 ID

在 App 启动时，调用 TUIVoIPExtension.setCertificateID 上报 前置准备 中获取的 VoIP 证书 ID。
import TUIVoIPExtension

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // 上报证书 ID
    TUIVoIPExtension.setCertificateID(1234)

    return true
}

步骤 4. 拨打 VoIP 通话

调用方式与方案一一致，请参考 方案一 > 拨打 VoIP 通话 章节。

步骤 5. 通过系统通话记录拨打通话

如果需要实现点击系统电话 > 最近通话列表中的通话记录，直接发起单人音视频通话，您需要在 Application 的生命周期回调函数使用 TUIVoIPExtension 组件中的 callWith 接口，具体示例如下：
说明：
仅支持单人音视频通话的直接拨打。
登录账户必须为同一个账户。
1. 在 iOS 13（及以后版本）上，使用了 SceneDelegate，且最低兼容版本到 iOS 13以下，需分别在 AppDelegate 和 SceneDelegate 中实现如下方法。
Swift
import TUIVoIPExtension

/// AppDelegate 中的实现，iOS 13 以前版本的处理
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) -> Void) -> Bool {
    TUIVoIPExtension.call(with: userActivity)
    return true
}

/// SceneDelegate 中的实现
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    for userActivity in connectionOptions.userActivities {
        TUIVoIPExtension.call(with: userActivity);
     }
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    TUIVoIPExtension.call(with: userActivity);
}
2. 在 iOS 13（及以后版本）上，未使用 SceneDelegate，只需要在 AppDelegate 实现如下方法。
Swift
import TUIVoIPExtension

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) -> Void) -> Bool {
    TUIVoIPExtension.call(with: userActivity)
    return true
}

常见问题

通用问题

收不到 VoIP Push，如何处理？

1. 检查 App 的运行环境和证书的环境是否一致，证书 ID 是否匹配，如果不一致，无法收到推送。
2. 请确认当前您登录的账号是否处于离线状态：按 home 键切后台、登录后主动杀进程退出。VoIP Push 目前只支持离线状态下的推送。
3. 检查 完成工程配置 中 Push Notifications capability 和 Background Modes 是否正确开启。
4. 尝试重启测试手机来清除系统缓存和内存（很重要）。

证书 ID 怎么填？开发环境和生产环境怎么区分？

在 IM 控制台上传证书时，开发环境和生产环境是分别上传、分别生成证书 ID 的。请根据您当前的 App 运行环境填写对应的证书 ID：
Debug 包 / TestFlight 测试 > 填开发环境的证书 ID
App Store 正式包 > 填生产环境的证书 ID

我的 App 需要同时上架中国大陆和海外 App Store，应该接哪一个？

中国大陆 App Store 对 Apple CallKit 的使用存在隐性限制，使用 pod 'AtomicXCore/WithAppleCallKit' 可能影响中国大陆版本的上架审核。建议：
方案 A（推荐）：中国大陆和海外使用同一套代码，统一接入不含 CallKit 的版本（参见 iOS 通话离线推送接入（中国大陆））。海外用户在 iOS 17.4+ 仍可获得 LCK 系统弹窗，体验不受影响，仅 iOS 17.3 及以下海外用户无法获得 CallKit 全屏来电。
方案 B：中国大陆和海外使用不同的 Bundle ID，分别打包。中国大陆版接入不含 CallKit 的版本，海外版接入本文档介绍的 CallKit 版本。

方案一相关问题

SDK 在 iOS 17.4+ 设备上是用 LCK 还是 CallKit？

接入了本文档的 pod 'AtomicXCore/WithAppleCallKit' 子库后，SDK 在 iOS 14.0 及以上全版本都使用 Apple CallKit，包括 iOS 17.4+ 设备。这是为了保证海外用户在所有系统版本上都能获得统一的原生电话级别来电体验。
如果您希望 iOS 17.4+ 设备改用 LCK（LiveCommunicationKit），可以改用不含 CallKit 的版本（参见 iOS 通话离线推送接入（中国大陆）），该版本会在 iOS 17.4+ 设备上自动使用 LCK，但 iOS 17.3 及以下设备就无法获得系统级全屏来电界面。

接入方案一后发现不够用，如何升级到方案二？

按以下步骤切换：
1. 在 Podfile 中移除 pod 'AtomicXCore/WithAppleCallKit'。
2. 添加 pod 'TUIVoIPExtension/CallKit'。
3. 执行 pod install。
4. 将代码中的 LoginStore.shared.setCertificateID(...) 替换为 TUIVoIPExtension.setCertificateID(...)。
5. 完成 方案二 > 开通服务 中的购买或试用流程。
注意：
两种方案不能同时使用，切换时请确保只保留一种依赖。

方案二相关问题

如何自集成 VoIP 推送功能？

如果您希望完全自定义推送逻辑，也支持您自己通过 SDK 的方式来集成 VoIP 推送能力，整体的方案设计如下：



相关流程说明：
1. 参考 申请 VoIP Push 证书 申请证书，并在 IM 控制台上传证书获取证书 ID。
2. 参考 Apple PushKit 使用获取设备 token。
3. 使用 IMSDK 的 setVOIP 接口向 IM 服务器上报设备 token。
4. 参考 Apple CallKit 展示推送弹窗。
5. 参考 TUICallKit 接口的使用 发起 VoIP 通话。
中国站