帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>推送服务（Push）>跑通 Demo>iOS

iOS

最近更新时间：2026-09-02 11:19:30
我的收藏

本页目录：

本文介绍如何在本地快速跑通腾讯云推送服务（TIMPush）的 iOS 体验 Demo，验证“注册推送 > APNs 下发 > 通知栏展示”的完整链路。

说明：
Demo 地址：Tencent-RTC/TIMPush_Demo（iOS/ 目录）。
Demo 为未配置任何参数的纯净模板，需按下文完成配置后方可编译运行。
产品能力说明请参见 推送服务产品概述。

前置准备（控制台）

跑通 Demo 前，请先在腾讯云控制台完成账号与 APNs 通道准备：
1. 创建应用：登录 即时通信 IM 控制台，在应用列表单击创建应用接入，记录生成的 SDKAppID。
2. 获取密钥：进入目标应用的应用配置，单击查看密钥，拷贝并妥善保管 SDKAppID 与客户端密钥 AppKey。
注意：
推送服务的客户端密钥与 Chat 的密钥不同，请勿混用。密钥属于敏感信息，请勿提交到代码仓库。
3. 配置 APNs 通道：在控制台推送服务页上传 APNs 推送证书（p8 / p12），记录生成的证书 ID（BusinessID）。

环境要求

项目
要求
开发工具
macOS + Xcode
依赖管理
CocoaPods（未安装可执行 sudo gem install cocoapods）
测试设备
iOS 真机（模拟器不支持 APNs，无法验证推送）
开发者账号
可配置签名、App Groups 的 Apple 开发者账号

跑通步骤

快捷方式：控制台下载预配置 Demo（推荐）

除 GitHub 纯净模板外，您还可以在控制台一键下载已按您的配置组装好的 Demo，下载入口为：推送服务 Push > 推送设置 > 下载推送 Demo。
该 Demo 已根据控制台配置完成以下注入：
pushdemo/TestPushViewController.m：已写入 kTIMPushSDKAppID / kTIMPushAppKey（下方「步骤 3」无需再手动填写）；
pushdemo/PushConstants.h：已写入 DEBUG 分支的 kAPNSBusiId，即 APNs 证书 ID（下方「步骤 4」中该项无需再填写）。
其余配置（pod install、签名 / Bundle ID / App Group 及 kTIMPushAppGroupKey）与您的 Apple 开发者账号和本机环境相关，仍需按下方步骤完成。

步骤 1：安装依赖

在 iOS/ 目录执行：
cd iOS
pod install

步骤 2：打开工程

使用 Xcode 打开生成的 pushdemo.xcworkspace。
注意：
必须打开 .xcworkspace，不能打开 .xcodeproj，否则找不到 Pod 依赖。

步骤 3：填写 SDKAppID 与 AppKey

打开 pushdemo/TestPushViewController.m，替换占位符：
static const int kTIMPushSDKAppID = 0;         // 改为您的 SDKAppID
static NSString * const kTIMPushAppKey = @"";  // 改为您的 AppKey

步骤 4：填写 BusinessID 与 App Group

打开 pushdemo/PushConstants.h，修改 DEBUG 分支中的占位符：
#ifdef DEBUG
#define kAPNSBusiId 11111             // 改为控制台 APNs 通道的证书 ID（BusinessID）
#define kTIMPushAppGorupKey @"xxxx"   // 改为您的 App Group Identifier（见步骤 5.2）
#endif

步骤 5：配置签名 / Bundle ID / App Group

5.1 签名与 Bundle ID（pushdemo 与 pushservice 两个 target 均需配置，位于 Signing & Capabilities）：
Team：选择您的 Apple 开发者团队。
Bundle Identifier：
主 App pushdemo：如 com.your-company.timpush.demo；
推送扩展 pushservice：必须为主 App Bundle ID 追加 .pushservice 后缀，如 com.your-company.timpush.demo.pushservice。
5.2 App Group 配置（主 App 与推送扩展共享数据所必需）：
1. 登录 Apple Developer，在 Identifiers > App Groups 创建 App Group，Identifier 以 group. 开头，如 group.com.your-company.timpush.demo。
2. 在 Xcode 中为 pushdemo 与 pushservice 两个 target 添加 App Groups 能力并勾选该 group.xxx；若无法勾选，请单击刷新按钮让 Xcode 重新生成描述文件。
3. 确认主 App target 已开启 Push Notifications 能力，否则收不到推送。
4. 将该 group.xxx 回填至 PushConstants.h 的 kTIMPushAppGroupKey（即步骤 4）。

步骤 6：运行验证

连接 iOS 真机，选择 pushdemo scheme 运行。注册成功后界面显示 RegistrationID；将 App 切至后台，通过控制台推送服务 Push > 接入测试发送一条测试推送，设备收到推送即代表全链路跑通。

注意事项

三处 App Group 一致：Apple Developer 后台、Xcode 两个 target、PushConstants.h 中的 App Group ID 必须完全一致。
证书环境匹配：APNs 证书环境（开发 / 生产）需与 App 安装包的签名环境匹配。
触发条件：离线推送仅在 App 处于后台或进程被杀死时触发，测试前请将 App 切至后台。

常见问题

编译报错 'TIMPushManager.h' file not found**：未执行 pod install，或误打开了 .xcodeproj，请改用 .xcworkspace。
报 Provisioning profile doesn't include the com.apple.security.application-groups entitlement：App Groups 能力未在 Xcode 成功启用，请重做步骤 5.2，必要时刷新描述文件。
App 能运行但收不到推送，请按以下顺序排查：
1.1 Signing & Capabilities 中是否已启用 Push Notifications 能力；
1.2 App Group 是否三处完全一致；
1.3 设备是否已授予 App 通知权限；
1.4 是否已获取到 RegistrationID（查看 Demo 界面与日志）；
1.5 仍无法定位，请参见 iOS 接入文档 - 收不到推送排障流程。

相关文档

iOS SDK 接入
厂商配置索引
推送排查工具
中国站