Meet Push Notifications Console
System & Services 进阶 20m

认识推送通知控制台

Meet Push Notifications Console

2023年6月5日

在 Apple 官方观看视频

一句话判断

Push Notifications Console 终于让推送通知的调试不再靠猜——发送通知、查看投递日志、验证认证 Token，一个网页工具全部搞定。如果你曾经为”推送为什么没收到”而头疼，这个工具就是你的解药。

这场 Session 讲了什么

Session 介绍了全新的 Push Notifications Console 工具。

发送通知（Send）：

  • 在网页界面直接向设备发送推送通知，用于端到端测试。
  • 输入 device token 和 payload，点击发送。
  • 支持自定义环境、推送类型、过期时间、优先级等参数。
  • 可以直接编辑 JSON payload。
  • 发送历史保存在侧边栏，可以复制重发并修改内容。

投递日志（Delivery Log）：

  • APNs 在推送通知经过其系统栈时记录事件。
  • 发送通知后，APNs 响应中包含新的 apns-unique-id 头。
  • 用这个 ID 在 Delivery Log 中搜索，可以看到通知的完整投递历史。
  • 每个事件描述发生了什么以及为什么——比如”因设备低电量模式而暂存”。
  • 支持通过常规 APNs API 发送的通知——只需记录响应中的 apns-unique-id。

Token 工具：

  • 认证 Token 生成器：输入私钥和 Key ID，自动生成 APNs 认证 Token。私钥只在浏览器中使用，不上传到服务器。
  • 认证 Token 验证器：粘贴已有的 Token，验证其有效性。如果无效，会告诉具体原因（如”签发时间太旧”）。
  • Device Token 验证器：检查 device token 的环境和有效性。

值得深挖的点

Delivery Log 是最有价值的调试能力。之前推送通知没收到时，开发者只能猜测原因——是 token 过期了？设备离线了？App 被卸载了？Delivery Log 给出了明确的答案。每个事件都有工具提示解释具体原因。常见的投递状态包括：设备低电量暂存、设备离线存储、App 已卸载丢弃等。

apns-unique-id 是连接发送和追踪的桥梁。每次发送推送后 APNs 返回这个唯一 ID，你需要在服务端记录它。之后用这个 ID 查询投递日志。这意味着你的服务端代码需要更新来保存这个 ID——这是一个小的工程改动，但解锁了完整的推送追踪能力。

Token 工具解决了认证调试的痛点。APNs 的 token-based 认证涉及 JWT、私钥、Key ID 等多个参数，手动验证这些参数是否正确配置很麻烦。Console 的生成器和验证器让你快速确认认证配置是否正确——特别是在刚接入 APNs 或更换认证密钥时。

代码片段

使用 Push Notifications Console 发送通知：

// Push Notifications Console 网页界面操作流程：
// 1. 打开 Console
// 2. Send 标签页
// 3. 输入 Device Token
// 4. 填写 payload：
//    Title: "Backyard Birds"
//    Subtitle: "重要更新"
//    Body: "知更鸟回来了！"
// 5. 设置推送类型、环境、优先级
// 6. 点击 Send

// 也可以切换到 Raw JSON 模式直接编辑 payload：
{
    "aps": {
        "alert": {
            "title": "Backyard Birds",
            "subtitle": "重要更新",
            "body": "知更鸟回来了！"
        },
        "sound": "default"
    }
}

追踪投递日志：

// 发送通知后，APNs 响应中包含新 header：
// apns-unique-id: ABC123-DEF456-...

// 在 Delivery Log 标签页搜索这个 ID
// 投递历史示例：
// 1. "received" - APNs 收到通知
// 2. "stored for device power considerations" - 设备低电量模式，暂存
// 3. "delivered" - 低电量模式关闭后投递成功

// 从 Console 发送的通知可以直接在 Send 页面看到投递状态
// 从服务端 API 发送的通知需要记录 apns-unique-id 然后手动查询

认证 Token 工具：

// Token 生成器：
// 输入：Private Key（从 Developer Portal 获取）
// 输入：Key ID
// 输出：有效的 APNs 认证 Token
// 注意：Token 有效期不超过 1 小时，需要定期轮换
// 私钥只在浏览器中使用，不上传

// Token 验证器：
// 输入：已有的认证 Token
// 输出：验证结果
//   - "valid" → Token 有效
//   - "issued at claim is too old" → Token 过期
//   - 其他错误原因

// Device Token 环境检查：
// 输入：Device Token
// 输出：Token 对应的环境（开发/生产）和有效性

最佳实践

  • 开发阶段用 Console 直接发送通知测试，比搭建完整后端快得多。
  • 服务端代码保存每次发送后的 apns-unique-id，用于后续投递追踪。
  • 推送没收到时第一时间查 Delivery Log，不要盲目重试。
  • 用 Token 验证器确认服务端使用的认证 Token 是否有效。
  • Device Token 可能变化（系统更新、重装 App），服务端需要处理注册失败并更新 token。
  • Token-based 认证的 JWT 有效期不超过 1 小时，确保服务端的轮换逻辑正确。

还有什么值得关注

  • Apple Push Notification service 每秒向设备交付数百万条通知。
  • Device Token 可能会变化，服务端必须处理 token 更新。
  • Push Notifications Console 是网页工具，不需要安装任何客户端。
  • Delivery Log 对所有通过 APNs API 发送的通知都可用——不只是 Console 发送的。
  • 低电量模式下的推送行为是系统级别的，你的 App 无法绕过这个限制。
WWDC 2023