iOS 16.4+ PWA原生推送通知实现指南

iOS 原生安装的 PWA 无法直接调用 Notification.requestPermission() 触发系统授权弹窗，必须通过 WebKit 消息桥接机制向宿主 Safari/iOS 环境发起权限请求，本文详解正确实现方式及关键注意事项。

需要明确的是，对于原生安装的 PWA 应用，直接调用 Notification.requestPermission() 触发系统授权弹窗的方式不可行。正确的做法是，必须通过 WebKit 消息桥接机制，向宿主 Safari 或 iOS 环境发起权限请求。以下将拆解正确的实现方式及需要格外留意的事项。

从 iOS 16.4 开始，苹果为“原生安装的 PWA”（即用户通过 Safari 的“添加到主屏幕”功能安装的应用）提供了有限的推送通知支持。但值得注意的是，这一能力并非通过标准的 Web Push API 实现，也不依赖 Service Worker 的 pushManager。其底层逻辑是通过 WebKit 提供的专用消息通道（webkit.messageHandlers）与 iOS 系统层进行通信。

正确触发通知权限弹窗的代码实现

需要在 PWA 的前端 JavaScript 代码中，主动检测并调用 iOS 特有的权限请求接口。代码实现清晰，如下所示：

// 检测是否运行在支持 iOS PWA 推送的环境（iOS 16.4+ + 原生安装）
if (
  window.webkit &&
  window.webkit.messageHandlers &&
  window.webkit.messageHandlers['push-permission-request']
) {
  // 标记环境支持 iOS 推送能力
  (window as any).iOSPushCapability = true;
  // 发起权限请求（这将触发系统级的通知授权弹窗）
  window.webkit.messageHandlers['push-permission-request'].postMessage('push-permission-request');
} else {
  console.warn('iOS PWA push permission is not available in this context.');
}

注意：该逻辑仅在用户将 PWA 添加到主屏幕并以全屏模式启动时生效。如果在普通 Safari 标签页中调用，不会报错，但会静默失败，无任何效果。

关键前提条件（缺一不可）

要使这套机制正常运行，需要满足以下前提条件：

• 应用必须通过 Safari 浏览器访问，且用户需点击“共享→添加到主屏幕”完成安装；
• iOS 系统版本 ≥ 16.4（iOS 17.4+ 稳定性更佳，推荐使用）；
• 在 Apple Developer Account 中，对应的 App ID 必须开启 "Push Notifications" 功能——即使未使用 APNs 后端，该开关也必须提前打开；
• 网站必须通过 HTTPS 提供服务，且 manifest.json 需包含有效的 display: "standalone" 或 "minimal-ui"；
• 切勿调用 Notification.requestPermission() —— 在 iOS PWA 环境下，该调用始终返回 'denied' 或无任何响应。

权限状态与后续处理

目前 iOS 不提供 JS API 查询推送权限的实际状态（如授权或拒绝），也无法获取设备令牌。一旦用户点击“允许”，系统会自动将设备注册到 Apple 推送服务（APNs）。后续需配合后端集成 APNs 发送通知（可使用通用 Push Certificate 或 Token-based Authentication）。

在实际开发中，建议在调用 postMessage 后，通过 UI 引导用户理解操作意图。例如，可提示用户：“正在请求通知权限，请在弹出窗口中点击‘允许’”，并设置合理超时提示，避免用户等待过久。

总结

总体而言，iOS PWA 的通知机制本质上是 WebKit 封装的面向原生系统的快捷入口，而非传统的“Web Push”。它绕过了 Web Push 的复杂流程，但带来了平台强约束。开发者可能需要放弃“跨平台统一逻辑”的预期。针对 iOS，需单独实现桥接调用，并严格满足相应的配置与运行时条件。只有将这些细节落实到位，才能确保 iOS 蓝色授权弹窗正常弹出。