在 iOS App 中接入 TIMPush 前，需要先完成 Apple Developer 侧的推送能力配置，并在腾讯云控制台上传 APNs 推送证书。完成本篇配置后，您将获得后续 SDK 接入所需信息。
前提条件
开始前，请确认您已具备以下条件：
条件 | 说明 |
Apple Developer 账号 | 用于创建 App ID、APNs 证书、描述文件和 App Groups。 |
iOS App 的 Bundle ID | 需要与 Xcode 工程主 App target 的 Bundle Identifier 完全一致。 |
腾讯云账号和即时通信 IM 应用权限 | 用于创建 Push 应用、上传 APNs 证书并获取后续 SDK 接入参数。 |
Xcode 工程 | 用于本文中的主 App target 配置。 |
Xcode 配置
确认 Bundle ID
Bundle ID 是 APNs 推送主题、Apple App ID、描述文件、Xcode 工程和腾讯云 APNs 证书配置之间的关键匹配项。请先在 Xcode 中确认主 App target 的 Bundle Identifier。
1. 打开 Xcode 工程。
2. 选择主 App target。
3. 单击 Signing & Capabilities。
4. 查看 Bundle Identifier。
请记录该值，后续在 Apple Developer Center 和腾讯云控制台中均需使用。
注意：
Bundle ID 不能使用通配符
*，否则无法使用 APNs 远程推送。开启 Push Notifications
确认 Bundle ID 后，建议继续在 Xcode 主 App target 中启用 Push Notifications，避免后续再回到 Xcode 重复操作。
1. 打开 Xcode 工程。
2. 选择主 App target。
3. 单击 Signing & Capabilities。
4. 单击 + Capability。
5. 添加 Push Notifications。
6. 确认 target 中出现 Push Notifications 能力。
注意：
无论使用 Xcode 自动签名还是手动签名，都需要在 Apple Developer Center 的 App ID 上启用 Push Notifications，详见下一组 Apple Developer Center 操作。自动签名会自动同步描述文件；手动签名还需要手动重新生成并下载描述文件。
Apple Developer Center 配置
说明：
本文配置流程可对照 Apple 官方 User Notifications - Setting up a remote notification server 操作；如遇页面变更，请以 Apple 官方最新文档为准。
创建或确认 App ID
App ID 用于声明你的 iOS App 能力。若你已经有与主 App Bundle ID 对应的 App ID（也就是你从上一个步骤中获取的 Bundle Identifier)，可直接确认其能力配置；如果没有，请参考下列步骤新建 App ID。
1. 登录 Apple Developer。
2. 进入 Certificates, Identifiers & Profiles。
3. 在左侧导航栏选择 Identifiers。
4. 单击 +。
5. 选择 App IDs，单击 Continue。
6. 选择 App，单击 Continue。
7. 填写 App ID 描述和 Bundle ID。
8. 单击 Continue 并确认创建。
开启 Push Notifications 能力
创建或确认 App ID 后，需要为该 App ID 开启 Push Notifications。
1. 在 Identifiers 列表中选择目标 App ID。
2. 切换到 Capabilities 标签。
3. 勾选 Push Notifications。
4. 单击 Save，并在弹窗中确认修改 App ID。
5. 完成后，Push Notifications 行右侧会出现 Configure 按钮。如果后续使用 p12 证书，需要从该按钮进入证书创建流程；如果使用 p8 证书，可以忽略该按钮。
完成后，请确认目标 App ID 的能力列表中已包含 Push Notifications。
选择 APNs 证书类型
Apple APNs 推送证书主要有 p8 和 p12 两种方式。新接入 TIMPush 时，推荐优先使用 p8 证书。
类型 | 推荐程度 | 适用场景 | 注意事项 |
p8 证书 | 推荐 | 新接入用户优先选择。 | |
p12 证书 | 传统方式 | 已有 p12 证书体系，或必须使用证书方式鉴权的项目。 | 证书有有效期，需要设置导出密码；自 2020 年起 Apple 已合并为同时覆盖 Sandbox 和 Production 的一张证书，无需分别为开发和生产创建。 |
创建 p8 证书（推荐）
p8 证书是 APNs Auth Key，用于腾讯云服务端向 APNs 鉴权。创建 p8 证书前，请确保已完成 App ID 和 Push Notifications 配置。
1. 登录 Apple Developer。
2. 进入 Certificates, Identifiers & Profiles。
3. 在左侧导航栏选择 Keys。
4. 单击 +创建新的 Key。
5. 输入 Key 名称。
6. 勾选 Apple Push Notifications service (APNs)。
7. （可选）单击 Configure 可进一步限定 Key 范围：
Environment：默认 Sandbox & Production（开发和生产共用），也可限定仅 Sandbox 或仅 Production。
Topic：默认 Team-scoped（同一 Team 下所有 App 可用），也可选 Topic-specific 并指定 Bundle ID。
新接入 TIMPush 若没有特殊安全诉求，保持默认即可。该能力为 Apple 2025 年 2 月推出的可选增强项，已有 Key 不受影响。
8. 单击 Continue。
9. 确认信息后，单击 Register。
10. 单击 Download 下载
.p8 文件。警告：
p8 文件只可下载一次，请妥善保存。若文件丢失，需要重新创建新的 Key。
请同时记录以下信息，后续上传到腾讯云控制台时需要填写：
信息 | 获取位置 |
Key ID | Apple Developer Center 的 Keys 列表对应行或 Key 详情页，10 位字符。  |
Team ID | Apple Developer 网站右上角账号信息，或 Account > Membership details 页面，10 位字符。  |
Bundle ID | 主 App 的 Bundle ID。 |
p8 文件 | 创建 Key 后下载的 .p8 文件。 |
创建 p12 证书，传统方式
如果您选择 p12 证书，请按以下步骤创建 APNs 推送证书。详细规则可参见 Apple 官方文档 Establishing a certificate-based connection to APNs。
1. 登录 Apple Developer。
2. 进入 Certificates, Identifiers & Profiles。
3. 在左侧导航栏选择 Identifiers。
4. 选择目标 App ID。
5. 在 Push Notifications 区域单击 Configure。
6. 在 Production SSL Certificate 区域单击 Create Certificate。自 2020 年起，Apple 的 SSL 证书已合并为同时覆盖 Sandbox 和 Production 的一张证书（即 Apple Push Notification service SSL (Sandbox & Production)），无需分别为开发和生产创建两张证书。
7. 按页面提示在 Mac 的 钥匙串访问 中生成 Certificate Signing Request（CSR）文件。
8. 上传 CSR 文件并生成 APNs 证书。
9. 下载证书并双击导入钥匙串。导入后，证书会出现在 登录 钥匙串的 我的证书 分类下。
10. 在 钥匙串访问 > 登录 > 我的证书 中找到名为
Apple Push Services: <您的 Bundle ID> 的证书，单击左侧 展开三角，确认证书下方挂着对应的 私钥。11. 同时选中 证书 和 私钥，右键选择 导出 2 项，文件格式选择 个人信息交换 (.p12)，并在弹窗中输入密码保护 p12 文件。
注意：
1. 必须连同私钥一起导出，否则生成的 p12 文件不能用于 APNs 鉴权。如果证书下方没有私钥，说明 CSR 不是在当前 Mac 生成的，请回到生成 CSR 的 Mac 重新导出。
2. 上传 p12 证书到腾讯云控制台时需要填写证书密码。无密码或密码错误可能导致推送失败。
创建或确认描述文件
描述文件（Provisioning Profile）用于将 App ID、证书和设备等签名信息绑定到 Xcode 工程。
说明：
如果您在 Xcode 中使用 Automatically manage signing（自动签名），Xcode 会在 App ID 启用 Push Notifications 后自动同步描述文件，本节可跳过。仅在使用手动签名，或 Xcode 自动签名失败需要手动处理时，才需按以下步骤创建描述文件。
如需手动管理，请在 Apple Developer Center 中创建：
1. 登录 Apple Developer。
2. 进入 Certificates, Identifiers & Profiles。
3. 在左侧导航栏选择 Profiles。
4. 单击 +创建新的 Profile。
5. 根据用途选择 iOS App Development 或 App Store。
6. 选择主 App 对应的 App ID。
7. 选择签名证书和设备（开发描述文件需要选择设备）。
8. 输入 Profile 名称并生成。
9. 下载并安装描述文件。
腾讯云控制台配置
在腾讯云控制台创建 Push 应用并开通服务
完成 Apple 侧证书准备后，需要在腾讯云控制台创建 Push 应用，并确认 Push 服务已开通。
1. 登录 腾讯云控制台。
2. 进入 即时通信 IM > 推送服务 Push > 概览。
3. 创建或选择目标 Push 应用。
4. 记录控制台展示的
SDKAppID 和客户端密钥。5. 在控制台确认 Push 服务状态，并按页面提示完成开通。注意，创建 Push 应用不等于 Push 服务已开通。
创建 Push 应用后，腾讯云控制台会自动创建相同
SDKAppID 的 Chat 应用。警告：
Push 的 Key 和 Chat 的 Key 不同，不能混用。后续调用
registerPush 使用 Push 的客户端密钥；Chat 登录使用 Chat 的密钥。registerPush 使用的客户端密钥 | Chat 登录使用的密钥 |
 |  |
上传 APNs 证书到腾讯云控制台
在腾讯云控制台上传 APNs 证书后，控制台会生成证书 ID。该证书 ID 是后续 SDK 接入文档中的
businessID。操作路径：
腾讯云控制台 > 即时通信 IM > 推送服务 Push > 推送设置 > 厂商配置 > iOS > 添加 APNs 证书。上传 p8 证书
1. 进入 iOS APNs 证书配置页面。
2. 选择 p8 证书类型。
3. 上传
.p8 文件。4. 填写 Key ID、Team ID 和 Bundle ID。
5. 根据控制台要求选择开发环境或生产环境。
6. 保存配置。
7. 记录控制台生成的证书 ID。
上传 p12 证书
1. 进入 iOS APNs 证书配置页面。
2. 选择 p12 证书类型。
3. 上传
.p12 文件。4. 填写导出 p12 时设置的证书密码。
5. 根据控制台要求选择开发环境或生产环境。
6. 保存配置。
7. 记录控制台生成的证书 ID。
注意：
上传证书时，请确认 Bundle ID 与主 App 的 Bundle Identifier 一致。发布到 App Store 的 App 需要使用生产环境证书配置。
触达统计资源配置（可选）
如果您仅需要接收普通离线推送，不统计推送触达率，跳过本节。
如果您需要统计推送触达率，请按下文在 Apple Developer Center 和 Xcode 中准备 App Groups；如果后续创建 Notification Service Extension，也需要为 Extension 准备对应的 App ID 和描述文件。
触达统计基于 iOS App Groups 在主 App 与 UNNotificationServiceExtension 之间共享数据。Extension 在通知送达前被系统调用，向 TIMPush 上报触达事件。
在 Apple Developer Center 创建 App Group ID
1. 登录 Apple Developer。
2. 进入 Certificates, Identifiers & Profiles。
3. 在左侧导航栏选择 Identifiers。
4. 选择 App Groups。
5. 单击 +创建新的 App Group。
6. 输入 App Group ID，例如
group.<您的 Bundle ID>，建议与主 App Bundle ID 关联，便于识别。7. 保存配置。
在 Apple Developer Center 绑定 App Groups
1. 将主 App 的 App ID 绑定到该 App Group。
2. 如果需要触达统计，请创建或确认 Extension App ID。Extension 的 Bundle ID 必须以主 App Bundle ID 为前缀（Apple 强制要求），例如主 App Bundle ID 为
com.example.myapp 时，Extension Bundle ID 应为 com.example.myapp.NotificationServiceExtension。3. 将 Extension App ID 绑定到同一个 App Group。
4. 为 Extension App ID 创建或确认描述文件。
在 Xcode 配置 App Groups
1. 打开 Xcode 工程。
2. 选择主 App target。
3. 单击 Signing & Capabilities。
4. 单击 + Capability，添加 App Groups。
5. 勾选在 Apple Developer Center 创建的 App Group ID。
6. 如果工程中已创建 Extension target，请在 Extension target 中勾选同一个 App Group ID。
配置完成检查
完成本篇配置后，请按顺序检查：
检查项 | 预期结果 |
Bundle ID 一致性 | 主 App 的 Bundle ID 已确认，且不是通配符；与 Apple App ID、APNs 证书、腾讯云控制台 APNs 配置绑定的 Bundle ID 完全一致。 |
Xcode Push 能力 | 主 App target 已在 Signing & Capabilities 中开启 Push Notifications。 |
Apple App ID | 已创建或确认主 App 的 App ID，并为该 App ID 开启 Push Notifications 能力。 |
APNs 证书 | 已创建 p8 或 p12 证书；若使用 p8，已保存 .p8 文件、Key ID、Team ID 和 Bundle ID；若使用 p12，已保存 .p12 文件、证书密码（导出时设置）和 Bundle ID。 |
描述文件 | 主 App 描述文件已创建或确认（自动签名由 Xcode 自动同步，手动签名需手动重新生成并下载）。 |
腾讯云 Push 应用 | 已在腾讯云控制台创建 Push 应用，并记录 SDKAppID 和客户端密钥 |
Push 密钥与 Chat 密钥区分 | 已了解 Push Key 与 Chat Key 不同，后续 registerPush 使用 Push 客户端密钥，Chat 登录使用 Chat 密钥，不会混用。 |
腾讯云 APNs 证书 | 已在腾讯云控制台上传 APNs 证书，并记录控制台生成的证书 ID（即 businessID）。 |
Push 服务开通状态 | 已在腾讯云控制台确认 Push 服务已开通（创建 Push 应用不等于服务已开通）。 |
App Group（可选） | 如需触达统计，已创建 App Group ID，并为主 App 和 Notification Service Extension 配置同一个 App Group；同时已准备 Extension 对应的 App ID 和描述文件。 |
