卸载跟踪 - (APNS) 苹果推送通知服务

关注
Avatar
Jared Ornstead
Updated
文档

苹果推送通知服务（APN）设置指南

配置苹果推送通知服务证书和供应配置文件，以便使用 Singular SDK 为 iOS 应用程序启用推送通知交付和卸载跟踪。

概述

前提条件

通过在 Apple Developer Member Center 创建 SSL 证书和配置文件启用 APNs 推送通知。

所需组件：

  • SSL 证书：与为推送通知配置的应用程序 ID 关联
  • 配置文件：授权设备在开发和测试期间运行应用程序
  • 苹果开发者帐户：创建证书所需的有效成员资格
  • Mac 电脑：钥匙串访问和证书生成所需的设备

Apple Developer Portal：所有证书和配置文件管理均在Apple Developer Member Center 中进行，请确保您在组织的开发人员团队中拥有适当的权限。

证书类型

Apple 为不同环境提供两种类型的 APN SSL 证书。

证书类型 环境 使用案例
开发 SSL 证书 沙盒 内部测试和开发构建
生产 SSL 证书 生产 应用程序商店发布和 TestFlight 构建

环境匹配至关重要：应用程序必须使用与其构建环境相匹配的证书。使用开发证书的生产应用程序将无法接收推送通知。

第 1 步：生成证书签名请求

在 Mac 上创建证书签名请求 (CSR) 文件，以验证 SSL 证书的创建。

创建 CSR 文件

使用钥匙串访问

通过 MacOS 上的 Keychain Access 应用程序生成 CSR。

  1. 打开钥匙串访问：导航至应用程序 → 实用工具 → 钥匙串访问，或使用 Spotlight 搜索 (Cmd+Space)
  2. 访问证书助手：在菜单栏中，选择钥匙串访问 → 证书助手 → 向证书颁发机构申请证书...
  3. 输入用户信息：
    • 用户电子邮件地址：输入您的电子邮件地址（在 Apple Developer 帐户中使用
    • 通用名称：输入描述性名称（例如，"YourCompany APNs Certificate
    • CA 电子邮件地址：留空
  4. 选择请求类型：选择 "保存到磁盘 "选项（手动创建证书需要该选项
  5. 保存 CSR 文件：点击 "继续"，并将 .certSigningRequest 文件保存到 Mac 上易于记忆的位置

Certificate Signing Request Creation

私钥存储：创建 CSR 时，Keychain Access 会自动生成并存储私钥。该私钥与你稍后从 Apple 下载的 SSL 证书配对。

步骤 2：创建或配置 App ID

创建新的 App ID 或配置现有的 App ID，以启用推送通知功能。

了解 App ID

应用程序 ID 结构

App ID 可唯一标识您的 iOS 应用程序，并且必须是支持推送通知的明确标识符（非通配符）。

格式：反向域符号（例如，com.yourcompany.appname)

需要明确的 App ID：通配符 App ID（包含 *）不能使用推送通知。如果已有通配符 App ID，请为支持推送的应用程序创建一个新的显式 App ID。

创建新的应用程序 ID

应用程序 ID 配置步骤

在启用推送通知的 Apple Developer 门户中创建新的 App ID。

  1. 访问开发者门户：导航至Apple Developer Member Center并登录
  2. 打开 "证书和标识符"：选择 "证书、标识符和配置文件
  3. 导航至 "标识符"：在左侧边栏选择 "标识符
  4. 选择平台：在左上角下拉菜单中，选择 "iOS 应用程序"（或在较新界面中选择 "iOS、tvOS、watchOS
  5. 创建标识符：点击 "+"按钮创建新的应用程序 ID

Create App ID Button

配置应用程序 ID 详细信息

填写 App ID 信息并启用推送通知功能。

  1. 选择类型：选择 "应用程序 ID"（非应用程序片段）
  2. 选择捆绑类型：选择 "应用程序 "作为类型
  3. 输入描述：提供有意义的名称（例如，"YourApp Production
  4. 设置捆绑包 ID：在 "应用程序 ID 前缀 "部分，使用默认团队 ID
  5. 输入明确的捆绑 ID：在捆绑 ID 字段中，输入与 Xcode 中完全一致的应用程序标识符（例如，com.yourcompany.appname)

Bundle ID Configuration

捆绑 ID 匹配：捆绑 ID 值必须与应用程序Info.plist 文件和 Xcode 项目设置中的标识符完全匹配。大小写敏感性很重要。

启用推送通知

在 "应用程序服务 "部分激活 "推送通知 "功能。

  1. 滚动到 "功能"：找到 "应用程序服务 "部分
  2. 启用推送通知：选中 "推送通知 "复选框
  3. 查看配置：单击 "继续 "并验证设置
  4. 确认应用程序 ID：验证标识符是否正确显示捆绑 ID
  5. 检查状态：确认推送通知显示为 "可配置
  6. 注册应用程序 ID：单击提交创建应用程序 ID

Enable Push Notifications

步骤 3：配置推送通知证书

为推送通知生成 SSL 证书，以便 APN 与您的应用程序通信。

访问应用程序 ID 设置

编辑应用程序 ID 配置

打开 App ID 设置，为开发和生产环境创建 SSL 证书。

  1. 导航至标识符：在 Apple Developer 门户，转到证书、标识符和配置文件 → 标识符
  2. 选择 App ID：点击已创建或要配置的应用程序 ID
  3. 编辑配置：点击 "编辑 "按钮（或在编辑模式下直接打开 App ID
  4. 找到 "推送通知"：滚动到功能列表中的 "推送通知 "部分

Edit App ID

创建开发 SSL 证书

生成开发证书

创建开发证书，用于在开发过程中测试推送通知。

  1. 开始创建证书：在 "推送通知 "部分，单击开发 SSL 证书下的 "创建证书..."。
  2. 查看说明：阅读 "关于创建证书签名请求 (CSR)" 信息
  3. 继续单击 "继续 "按钮
  4. 上传 CSR：单击 "Choose File...（选择文件...）"并选择在步骤 1 中创建的 .certSigningRequest 文件
  5. 生成：单击 "继续"（或 "生成"）创建证书

Push Notifications Certificate Options

Upload CSR

下载并安装证书

下载 SSL 证书并将其安装到 Mac 钥匙串中，以便与推送通知一起使用。

  1. 下载证书：点击 "下载 "按钮，将 .cer 文件保存到 Mac 中。
  2. 完成过程：点击 "完成 "关闭证书创建流程
  3. 安装证书：找到下载的 .cer 文件并双击将其添加到钥匙串
  4. 验证安装：打开钥匙串访问并导航至 "我的证书 "类别
  5. 找到证书：找到 "Apple Development iOS Push Services: your.bundle.id "证书和相关私钥

证书配对：下载的证书会自动与 CSR 创建过程中生成的私钥配对。 两者都必须存在于钥匙串中，推送通知才能正常工作。

将证书导出为 .p12

生成 P12 文件

将证书和私钥导出为 .p12 文件，以便上传到推送通知服务（如 Singular）。

  1. 打开钥匙串访问：导航至 "我的证书 "类别
  2. 展开证书：单击 "Apple Development iOS Push Services "证书旁边的三角形，显示私钥
  3. 选择两个项目：按住 Command 键并点击，同时选择证书和私钥
  4. 导出：右键单击选择并选择 "导出 2 项...
  5. 命名文件：使用描述性名称保存（例如，"YourApp_Development_APNs.p12）
  6. 选择格式：确保选择 "个人信息交换 (.p12)" 作为文件格式
  7. 设置密码：输入强密码以保护 .p12 文件
  8. 确认导出：单击 "确定 "并在出现提示时输入 Mac 登录密码

安全警告：.p12 文件包含你的私人密钥和证书。请妥善保存，切勿提交到公共存储库。记住密码--它无法恢复。

创建生产 SSL 证书

生成生产证书

重复证书创建过程，创建 App Store 发布所需的生产 SSL 证书。

  1. 返回 App ID 设置：返回 Apple Developer 门户中的 App ID 配置
  2. 生产证书：在推送通知部分，单击生产 SSL 证书下的 "创建证书..."。
  3. 遵循相同流程：上传 CSR、生成证书、下载并安装到钥匙串中
  4. 导出生产 P12：导出为带有描述性名称的 .p12（例如，"YourApp_Production_APNs.p12
  5. 安全存储：安全存储生产证书与开发证书

需要生产证书：提交到 App Store 并通过 TestFlight 发布的应用程序必须使用生产 SSL 证书。开发证书将在生产环境中失效。

步骤 4：创建供应配置文件

生成供应配置文件，授权设备在开发和测试阶段运行应用程序。

了解供应配置文件

配置文件类型

供应配置文件会将您的应用程序 ID、证书和注册设备连接起来，以便安装和测试应用程序。

配置文件类型 目的 设备限制
iOS 应用程序开发 在注册设备上进行内部测试 每个配置文件最多 100 台设备
临时 分发给开发团队以外的测试人员 每个配置文件最多 100 台设备
应用程序商店 应用商店分发和 TestFlight 无限制（所有设备）

创建开发配置文件

开发配置文件设置

为推送通知测试创建 iOS 应用程序开发供应配置文件。

  1. 访问供应配置文件：在 Apple Developer 门户，导航至证书、标识符和配置文件 → 配置文件
  2. 创建新预案：单击 "+"按钮开始创建配置文件
  3. 选择类型：在 "开发 "部分选择 "iOS 应用程序开发
  4. 继续单击 "继续 "按钮
  5. 选择应用程序 ID：在下拉菜单中，选择为推送通知配置的应用程序 ID
  6. 继续单击继续按钮

配置配置文件详细信息

选择证书、设备并命名配置文件。

  1. 选择证书：选中与 App ID 关联的 iOS 开发证书
  2. 继续单击继续按钮
  3. 选择设备：选中要测试推送通知的所有设备（必须在设备部分预先注册
  4. 继续单击继续按钮
  5. 命名配置文件：输入描述性名称（例如，"YourApp Development Push Testing
  6. 生成配置文件：单击生成按钮

设备注册：测试设备必须先在 Apple Developer 门户注册，然后才能添加到配置文件。在 "设备 "部分按 UDID 注册设备。

安装预配置文件

下载并安装供应配置文件，以便在 Xcode 中使用。

  1. 下载预案：单击下载按钮保存 .mobileprovision 文件
  2. 安装配置文件：双击下载的 .mobileprovision 文件将其添加到 Xcode 中
  3. 验证安装：打开 Xcode → 首选项 → 帐户 → 查看详细信息，以确认配置文件是否出现
  4. 在项目中选择：在 Xcode 项目设置中，在 "签名和功能 "下选择预配置文件

预案过期：预配置文件一年后过期。在 Apple Developer 门户更新过期的配置文件，并下载新的 .mobileprovision 文件。

验证和测试

通过测试向开发设备推送通知，验证 APN 配置是否正确。

配置检查表

测试前验证

在测试推送通知前，确认所有组件配置正确。

  • 应用程序 ID：启用推送通知功能的显式应用程序 ID
  • SSL 证书：开发和生产证书已创建并导出为 .p12
  • 配置文件：在 Xcode 中安装了开发配置文件，其中包含正确的应用程序 ID 和设备
  • 捆绑 ID 匹配：Xcode 项目捆绑 ID 与应用程序 ID 标识符完全匹配
  • 功能：在 Xcode 中启用推送通知功能 签名和功能
  • 钥匙串：Mac钥匙串 "我的证书 "中存在带有私钥的证书

测试推送通知

测试步骤

发送测试推送通知以验证 APN 配置。

  1. 构建和安装：使用开发配置文件构建应用程序并安装到测试设备上
  2. 请求权限：启动应用程序并在出现提示时授予推送通知权限
  3. 注册设备令牌：在控制台日志中验证应用程序是否收到 APN 设备令牌
  4. 发送测试通知：使用 APNs 测试工具或推送服务发送测试通知
  5. 验证发送：确认通知出现在设备上

常见问题

问题 原因 解决方法
未收到设备令牌 功能中未启用推送通知 在 Xcode 签名和功能选项卡中启用推送通知
未找到证书错误 钥匙串中缺少私钥 从创建 CSR 的原始 Mac 重新导出包含私钥的证书
推送通知未送达 环境错误（开发环境与生产环境） 验证证书类型是否与构建配置相匹配
配置文件无效 配置文件过期或设备未注册 更新配置文件并确保设备已注册
捆绑 ID 不匹配 Xcode 捆绑 ID 与应用程序 ID 不匹配 更新 Xcode 中的捆绑 ID，使其与应用程序 ID 标识完全匹配

测试工具：在开发过程中使用 Xcode 中的 Apple 推送通知控制台或第三方工具（如 Pusher、Knuff 或 curl 命令）发送测试通知。

下一步

配置好 APN 后，在应用程序中集成推送通知处理功能，并配置 Singular 进行卸载跟踪。

集成指南

完成设置

  • iOS 推送实施：在 iOS 应用程序代码中实施 APN 注册和通知处理
  • Singular SDK 集成：按照Singular iOS SDK 实施指南启用卸载跟踪
  • 将证书上传到 Singular：将 .p12 证书上传到 Singular 的应用程序配置，用于卸载跟踪
  • 测试卸载跟踪：在生产发布前验证卸载检测是否正常工作

生产部署

应用程序商店提交要求：

  • 生产证书：为 App Store 构建使用生产 SSL 证书
  • App Store 配置文件：创建并使用 App Store Distribution 配置文件
  • 代码签名：确保在 Xcode 存档设置中选择正确的证书和配置文件
  • TestFlight：TestFlight构建使用生产环境--使用生产证书进行测试