Apple Wallet自定义推送通知不显示问题排查求助

我已实现Apple Wallet Pass生成及静默通知更新功能，运行正常。但发送营销类自定义推送通知时，通知发送成功但手机端无显示。使用TypeScript开发，部署在Firebase Cloud Functions，采用apn库构建发送通知。

正常运行的静默通知实现代码 #

const options: apn.ProviderOptions = {
  token: {
    key: fs.readFileSync("./certs/APNs_AuthKey_7YYF346FU5.p8"),
    keyId: "******",
    teamId: "******",
  },
  pfx: fs.readFileSync("./certs/private_key.pem"),
  cert: fs.readFileSync("./certs/certificate.pem"),
  production: true,
  rejectUnauthorized: true,
};

const apnProvider = new apn.Provider(options);

async function sendSilentPushNotification(
  deviceTokens: string[],
  serialNumber: string
) {
  try {
    const notification = new apn.Notification();

    notification.topic = "pass.com.digital.passmaker";

    notification.payload = {
      aps: {
        "content-available": 1,
      },
      serialNumber,
    };

    notification.priority = 5;
    return await apnProvider.send(notification, deviceTokens);
  } catch (error) {
    logger.error("Apple Notification error: " + error);
    return error;
  }
}

待修复的自定义推送通知代码 #

async function sendCustomPushNotification(
  deviceTokens: string[],
  serialNumber: string,
  title: string,
  body: string,
  category?: string,
  badge?: number
) {
  try {
    const notification = new apn.Notification();

    notification.topic = "pass.com.digital.passmaker";

    // Set the title and body of the notification
    notification.alert = {
      title: title,
      subtitle: "Pass Update",
      body: body,
    };

    // Set the sound to play when the notification is received
    notification.sound = "default";

    // Set the badge number on the app icon (optional)
    if (badge !== undefined) {
      notification.badge = badge;
    }

    notification.contentAvailable = true;
    notification.mutableContent = true;
    notification.aps.category = category;
    notification.aps.alert = {
      title: title,
      body: body,
    };
    notification.aps.badge = badge;
    notification.aps["content-available"] = 1;
    notification.aps["launch-image"] =
      "https://banner2.cleanpng.com/20180423/gkw/kisspng-google-logo-logo-logo-5ade7dc753b015.9317679115245306313428.jpg";

    // You can still include the serialNumber in the custom payload
    notification.payload = {
      serialNumber: serialNumber,
      aps: {
        "content-available": 1,
        "mutable-content": 1,
        "interruption-level": "time-sensitive",
      },
    };

    // Set to high priority
    notification.priority = 10;

    return await apnProvider.send(notification, deviceTokens);
  } catch (error) {
    logger.error("Apple Notification error: " + error);
    return error;
  }
}

问题排查与修复方案 #

你的自定义推送代码存在aps字段重复设置和payload结构错误的问题，导致APNs解析异常，通知无法正常显示。具体修复点如下：

• 避免重复设置aps字段：apn库会自动将notification.alert、notification.sound、notification.badge等属性映射到aps结构中，无需手动给notification.aps赋值，重复设置会覆盖正确配置。
• payload中不要嵌套aps：payload应只包含自定义数据（如serialNumber），aps部分由apn库通过notification的属性自动生成，手动在payload中嵌套aps会导致结构混乱。
• 移除不必要的content-available设置：营销类通知不需要content-available（这是静默通知的标识），保留会让系统优先处理后台更新而非显示通知。
• 修正launch-image配置：launch-image是应用通知的配置，Wallet通知不支持该字段，需移除。

修复后的代码：

async function sendCustomPushNotification(
  deviceTokens: string[],
  serialNumber: string,
  title: string,
  body: string,
  category?: string,
  badge?: number
) {
  try {
    const notification = new apn.Notification();

    notification.topic = "pass.com.digital.passmaker";

    // 设置通知标题、副标题、内容
    notification.alert = {
      title: title,
      subtitle: "Pass Update",
      body: body,
    };

    // 设置通知音效
    notification.sound = "default";

    // 设置应用图标角标（可选）
    if (badge !== undefined) {
      notification.badge = badge;
    }

    // 如需支持通知扩展，保留mutableContent；否则可移除
    notification.mutableContent = true;
    // 设置通知分类（如果已在Pass中配置对应category）
    if (category) {
      notification.category = category;
    }

    // 自定义payload仅包含业务数据，不要嵌套aps
    notification.payload = {
      serialNumber: serialNumber,
    };

    // 营销类通知需设置高优先级
    notification.priority = 10;

    return await apnProvider.send(notification, deviceTokens);
  } catch (error) {
    logger.error("Apple Notification error: " + error);
    return error;
  }
}

额外检查点：

• 确认Pass的pass.json中已配置对应的notificationTypes为["alert"]，否则Wallet不会显示通知。
• 验证设备是否开启了Wallet的通知权限，确保没有被静音或屏蔽。
• 检查APNs证书/密钥的权限，确认包含推送通知权限，且环境（生产/沙箱）与代码中production配置一致。

内容的提问来源于stack exchange，提问作者DholaSain