通知中的概念
iOS 与 iPadOS 上的 Web Push(16.4+)
发布于 更新于
Web Push 让主屏幕 Web App 在 iOS 与 iPadOS 16.4(2023-03)及之后的版本中接收通知。它沿用桌面端的 Push API、Notifications API 和 Service Worker,由 Apple Push Notification service 投递。用户必须先安装应用,再点按控件请求权限,才能使用推送。iPhone 的 Safari 标签页没有 Notification 接口,未安装的站点无法请求权限。
工作原理
链接到“工作原理”一节WebKit 把整个特性绑定在安装上。用户从分享菜单选择「添加到主屏幕」且 manifest 的 display 成员为 standalone 或 fullscreen,或页面带有 apple-mobile-web-app-capable meta 标签时,站点成为主屏幕 Web App;两者都没有时,图标只是一个主屏幕书签,自 16.4 起在用户的默认浏览器中打开,而浏览器标签页里没有推送(Web Push for Web Apps on iOS and iPadOS,webkit.org)。browser-compat-data 把同一门槛表述为“非默认的 display 值”。自 16.4 起第三方浏览器也可以提供同样的分享菜单项,生成的应用无论由哪个浏览器添加都以 Web App 方式打开。
Safari 标签页暴露了什么
链接到“Safari 标签页暴露了什么”一节browser-compat-data 把 iOS 上的 Notification 记为 16.4、部分支持,并附两条备注:除非页面是 manifest 带非默认 display 的主屏幕 Web App,否则接口未定义;通知只能由 Service Worker 发出(api.Notification 的 safari_ios)。标签页里的 Notification.requestPermission() 抛出的是 ReferenceError,不是被拒绝的 Promise;new Notification() 在该平台上完全没有可用路径;在脚本中,registration.showNotification() 是显示通知的唯一方式。例外是 Declarative Web Push 消息(18.4+,见下文),由浏览器自行显示,不需要 JavaScript。
权限、订阅与投递
链接到“权限、订阅与投递”一节在已安装的应用内,权限请求必须跟随直接的用户交互,例如点按订阅按钮;随后 iOS 显示系统通知提示,用户在「设置 > 通知」里按 Web App 管理结果,与原生应用一样。pushManager.subscribe() 要求 userVisibleOnly: true 和 VAPID applicationServerKey;返回的 endpoint 位于 *.push.apple.com 主机上,按白名单放行推送端点的服务器必须允许它。WebKit 会撤销 push 事件没有产生可见通知的订阅(Meet Web Push,webkit.org),所以处理函数吞掉消息,或在 showNotification() 之前失败,都会丢失整个订阅,不只是漏掉一条提醒。
2026-10-20 的 OpenPWA 真机测试使用 iOS 18.6.2。在尚未请求过权限的主屏应用中,点按后调用 Notification.requestPermission(),请求挂起了 2068 ms,直到操作者回应系统提示,结果为 "granted";在 zh-CN 界面下提示文字为「“Perm Test”想给你发送通知」(研究正文,实验记录 N54、N59)。一次授权同时把注册上的与 window.pushManager 上的 permissionState 都变为 granted。
通知与「专注模式」集成,manifest id 与用户所取名称相同的 Web App 在多台设备之间同步专注设置。Badging API(navigator.setAppBadge())在同一版本为主屏幕 Web App 发布,通知权限授予后即显示角标。
Declarative Web Push(18.4+)
链接到“Declarative Web Push(18.4+)”一节iOS 与 iPadOS 18.4 为主屏幕 Web App 增加了第二种形态,Safari 18.5 把它带到 macOS:window.pushManager(BCD api.Window.pushManager:Safari 18.4)让页面无需 Service Worker 即可订阅,而符合声明式 JSON 格式("web_push": 8030 加一个 notification 对象)的推送消息由浏览器直接显示,不运行任何 JavaScript。存在 Service Worker 时它仍可修改通知;若其处理函数失败,声明式消息作为兜底显示,所以上述撤销规则在这条路径上不会生效(Meet Declarative Web Push,webkit.org)。同一篇文章写明,作用域为网站根目录(「scoped to the root level of your website domain」)的已注册 Service Worker 与 window 对象共享同一个推送订阅;作用域为子路径的 worker 不在这句话的范围内。
OpenPWA 在 iOS 18.6.2 上测试的主屏应用,Service Worker 作用域是子路径(/demo/ 与 /lab/ 下的一个实验室路径)。从注册建立订阅后,调用 window.pushManager.getSubscription() 得到 null,没有返回那个订阅;根作用域的 worker 没有测试。另外,普通 Safari 标签页中也暴露 window.pushManager,而那里没有 Notification 与 PushManager,所以 'pushManager' in window 并不能说明推送可用(研究正文,实验记录 N03、N33、N41)。
已安装应用中的通知点按
链接到“已安装应用中的通知点按”一节browser-compat-data 把 ServiceWorkerGlobalScope 上的 notificationclick 记为 iOS 版 Safari 不支持(api.ServiceWorkerGlobalScope.notificationclick_event,version_added: false)。在关于这条记录的 BCD issue 中,一位 BCD 贡献者解释说,采集器在 Service Worker 中检测 "onnotificationclick" in self,这一检测在 iOS 16、17、18 上都失败;同时有开发者报告该事件在已安装应用中会触发(mdn/browser-compat-data#22959,github.com)。WebKit 的 268797 号缺陷仍未关闭,其中有报告称用户点按通知时如果应用没有存活页面,事件不触发(Bug 268797,bugs.webkit.org)。
这个属性取决于控制 worker 的上下文,因此两种报告可以同时成立。在 iOS 18.6.2 上,同一个 worker 脚本由 Safari 标签页控制时 'onnotificationclick' in self 为 false,由主屏应用控制时为 true;在六次测试点按中(每次都有窗口存活),notificationclick 都在应用中触发了(见下方实测笔记)。无条件注册处理函数,不要用在已安装应用之外运行的特性检测来决定是否注册。
支持位置
链接到“支持位置”一节macOS Ventura 上的 Safari 16.1 最先发布 Web Push(2022-10;WebKit 的 iOS 16.4 文章写明了这个版本),通过 webpushd 守护进程投递,Safari 无需运行。iOS 与 iPadOS 16.4 随后跟进,仅限主屏幕 Web App(两者都有 compat 数据)。BCD 记录 Android WebView 与其他应用内的 iOS WebView 都没有 Push API(api.PushManager)。Android 版 Chrome 自 42 版起无需安装即可在浏览器标签页中使用推送,但 Samsung Internet 与 Android 版 Opera 在无痕模式下不显示通知(BCD api.Notification)。
在 iOS 上,这些示例只在已安装的应用内有效;在其他平台,它们需要支持推送的浏览器和 HTTPS 页面。
把未安装的 iPhone 访客引导到安装指引
链接到“把未安装的 iPhone 访客引导到安装指引”一节'Notification' in window 这一测试在 iOS 上就是安装检查:标签页里为 false,主屏幕应用里为 true。它在其他平台上也是正确的第一步,所以不需要任何平台嗅探。
async function enablePush(registration, applicationServerKey) { if (!('Notification' in window)) { showAddToHomeScreenGuidance(); // iOS 标签页或应用内嵌网页视图:先安装 return null; } const permission = await Notification.requestPermission(); if (permission !== 'granted') return null; return registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey });}从点按处理函数里调用 enablePush():WebKit 要求权限请求紧跟直接的用户交互,iOS 18.6.2 设备测试中提示也是在点按之后出现的。
在 push 处理函数中兑现 userVisibleOnly 的承诺
链接到“在 push 处理函数中兑现 userVisibleOnly 的承诺”一节对经典(非声明式)推送消息,每个 push 事件都必须以 showNotification() 结束,包括错误路径,否则 WebKit 撤销订阅。一条通用的兜底通知比什么都不显示更安全。
self.addEventListener('push', (event) => { event.waitUntil((async () => { let payload = { title: '有新内容', body: '' }; try { payload = event.data.json(); } catch { // 载荷格式错误:仍然要显示点什么,否则订阅会被撤销 } await self.registration.showNotification(payload.title, { body: payload.body }); })());});保留 try/catch,避免服务端 bug 发来格式错误的 body 后,让所有 iPhone 用户悄悄退订。这项防护在 iOS 上比其他平台更重要。
查询建立订阅时用的那个推送管理器
链接到“查询建立订阅时用的那个推送管理器”一节检测订阅时使用的管理器;单独检测 PushManager 接口不够。window.pushManager 是声明式路径,但在 iOS 18.6.2 上它也暴露在无法使用推送的 Safari 标签页里,而且 worker 作用域低于站点根目录时,它不会返回 worker 的订阅。先检查 Notification,再优先使用活跃的注册。
async function getPushManager() { if (!('Notification' in window)) return null; // iOS 标签页或 WebView:window.pushManager 仍可能存在 const registration = 'serviceWorker' in navigator ? await navigator.serviceWorker.getRegistration() : undefined; if (registration?.active) return registration.pushManager; // 经典 Web Push 订阅时用的管理器 return 'pushManager' in window ? window.pushManager : null; // Declarative Web Push,Safari 18.4+}没有任何注册时 getRegistration() 以 undefined 兑现;navigator.serviceWorker.ready 在这种情况下会永远等待,这正是探测避开它的原因。worker 作用域低于站点根目录时,在两种管理器之间迁移的应用必须对自己用过的那个调用 getSubscription(),否则可能读到 null 并再次订阅。
另请参阅
链接到“另请参阅”一节- Web Push for Web Apps on iOS and iPadOS(webkit.org)
- Meet Declarative Web Push(webkit.org)
- Push API(w3.org)
- Web Push 与 PushManager.subscribe()
- iOS 添加到主屏幕
- Notification.requestPermission()
- Badging API
- iOS 18.6.2 主屏 Web 应用真机实测
- mdn/browser-compat-data#22959(github.com)
规范
| 规范 | 状态 |
|---|---|
| Web Push(网页推送) | W3C |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 支持 | 42 | 高 | 来源 | 1 |
| Chrome (Android)# | 支持 | 42 | 高 | 来源 | 23 |
| Edge (Desktop)# | 支持 | 17 | 高 | 来源 | 4 |
| Firefox (Desktop)# | 支持 | 44 | 高 | 来源 | 5 |
| Firefox (Android)# | 支持 | 48 | 高 | 来源 | 6 |
| Safari (macOS)# | 支持 | 16 | 高 | 来源 | 7 |
| Safari (iOS)# | 支持 | 16.4 | 高 | 来源 | 8 |
| Samsung Internet# | 支持 | 4.0 | 高 | 来源 | 910 |
| WebView (Android)# | 不支持 | — | 高 | 来源 | 11 |
| Safari(iOS) · 声明式 Web Push# | 支持 | 18.4 | 中 | 来源 | 121314 |
- 必须传入带 `applicationServerKey` 值的 `options` 参数。
- 必须传入带 `applicationServerKey` 值的 `options` 参数。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 必须传入带 `applicationServerKey` 值的 `options` 参数。
- 从 Firefox 72 起,只能在响应用户手势(例如 `click` 事件)时调用。
- 从 Firefox Android 79 起,只能在响应用户手势(例如 `click` 事件)时调用。
- macOS Ventura 及更高版本支持通知。
- 添加到主屏幕的 Web 应用支持通知。
- 必须传入带 `applicationServerKey` 值的 `options` 参数。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- browser-compat-data 未记录 WebView Android 的支持。
- WebKit 的 Safari 18.4 文章写道:"Declarative Web Push is now available on iOS and iPadOS 18.4 for web apps added to the Home Screen."(译文:声明式 Web Push 现已在 iOS 与 iPadOS 18.4 上提供给添加到主屏幕的 Web 应用。)文章把声明式 Web Push 描述为不需要 service worker 也能显示的推送通知。
- browser-compat-data 没有声明式 Web Push 的条目。最接近的键 `api.Window.pushManager` 记录 iOS 版 Safari 18.4 起支持,并标记为实验性。
- OpenPWA device test, 2026-10-20, iPhone 16 Pro, iOS 18.6.2 (22G100):普通 Safari 标签页中同样暴露 `window.pushManager`;在 Service Worker 作用域为子路径的主屏应用中,worker 的注册已有订阅,`window.pushManager.getSubscription()` 却返回 `null`,与 WebKit「只有根作用域的 worker 与 window 共享订阅」的说法一致。
生态与商业政策
| 主体 | 类型 | 场景 | 状态 | 赞助 | 备注 |
|---|---|---|---|---|---|
| Apple Push (APNs)# | delivery_policy | iOS | 部分支持 | 否 | iOS 上的 Web Push 要求用户先把应用添加到主屏幕。 |
在线试用
在 OpenPWA 演示应用中运行此能力: /demo/#push