Node-apn 2.0 版本重大更新解析

原创于 2025-06-09 09:20:11 发布 · 363 阅读

3 ·

CC 4.0 BY-SA版权

Node-apn 2.0 版本重大更新解析

node-apn :calling: Apple Push Notification module for Node.js 项目地址: https://gitcode.com/gh_mirrors/no/node-apn

前言

Node-apn 是一个用于与苹果推送通知服务(APNs)交互的 Node.js 模块。在 2.0 版本中，该项目进行了彻底的重构，以适配苹果公司的新协议。本文将深入解析这些变化，帮助开发者顺利迁移到新版本。

核心变更概览

1. 主要类名变更

apn.Connection 更名为 apn.Provider：这个变化反映了苹果推送服务架构的演变，更准确地描述了该类的功能定位。

2. 废弃组件

移除了 apn.Feedback 服务：苹果在新协议中已不再提供设备反馈服务，开发者需要通过其他方式处理无效的设备令牌。

3. 设备令牌处理

移除了 apn.Device 类：现在所有令牌都直接使用十六进制编码的字符串表示。
新增 apn.token 工具：用于验证令牌格式并在需要时将 Buffer 转换为字符串。

4. 通知发送机制

必须为通知指定 topic 字段：这是苹果新协议的要求，通常对应应用的 bundle identifier。
pushNotification(notification, tokens) 简化为 send(notification, recipients)：接口更加简洁。
send 方法返回 Promise：可以更好地处理异步操作结果。

代码迁移指南

旧版本(v1.7)示例

function setup() {
  var connection = new apn.Connection(configuration);
  connection.on("transmissionError", notificationFailed);
}

func sendNotification(user) {
  var note = new apn.Notification();
  note.alert = "Hello " + user.name;

  connection.pushNotification(note, user.token);
}

新版本(v2.0)实现

function setup() {
  let connection = new apn.Provider(configuration);
}

function sendNotification(user) {
  let note = new apn.Notification();
  note.alert = "Hello " + user.name;
  note.topic = "io.github.node-apn.test"

  connection.send(note, user.token).then( (response) => {
    response.sent.forEach( (token) => {
      notificationSent(user, token);
    });
    response.failed.forEach( (failure) => {
      if (failure.error) {
        // 传输层错误(如网络问题)
        notificationError(user, failure.device, failure.error);
      } else {
        // `failure.status` 是HTTP状态码
        // `failure.response` 是JSON响应体
        notificationFailed(user, failure.device, failure.status, failure.response);
      }
    });
  });
}