跳转到内容

通知中的概念

iOS 与 iPadOS 上的 Web Push(16.4+)

发布于 更新于

所有核心浏览器均可用W3C

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 方式打开。

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 发布,通知权限授予后即显示角标。

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(网页推送)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
  1. 必须传入带 `applicationServerKey` 值的 `options` 参数。
  2. 必须传入带 `applicationServerKey` 值的 `options` 参数。
  3. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  4. 必须传入带 `applicationServerKey` 值的 `options` 参数。
  5. 从 Firefox 72 起,只能在响应用户手势(例如 `click` 事件)时调用。
  6. 从 Firefox Android 79 起,只能在响应用户手势(例如 `click` 事件)时调用。
  7. macOS Ventura 及更高版本支持通知。
  8. 添加到主屏幕的 Web 应用支持通知。
  9. 必须传入带 `applicationServerKey` 值的 `options` 参数。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  11. browser-compat-data 未记录 WebView Android 的支持。
  12. 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 也能显示的推送通知。
  13. browser-compat-data 没有声明式 Web Push 的条目。最接近的键 `api.Window.pushManager` 记录 iOS 版 Safari 18.4 起支持,并标记为实验性。
  14. 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_policyiOS部分支持否iOS 上的 Web Push 要求用户先把应用添加到主屏幕。

源数据: /compatibility/web-push.json · 全球使用占比: 96 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-20 · 置信度: 中 (由来源计算)