添加推送通知
发布于
Web Push 让服务器在应用关闭后仍能发送消息、唤醒用户设备。页面先把 Service Worker 订阅到浏览器的推送服务,
服务器再向订阅 endpoint 发送请求。worker 收到 push 事件后显示系统通知。消息由 Push API 送到 worker,
Notifications API 负责显示通知。
你需要一个已激活的 Service Worker(没有的话先做入门)、一个 HTTPS 源, 以及服务端的一对 VAPID 密钥。Push API 自 2023-03 起在各浏览器可用;Safari 只向主屏幕 Web 应用 投递,始于 iOS 与 iPadOS 16.4,macOS Ventura 上的 Safari 16.1 同样支持。各浏览器的明细见 Web Push 网页推送支持。
1. 先确认支持,再提供按钮
链接到“1. 先确认支持,再提供按钮”一节从 ServiceWorkerRegistration.pushManager 访问推送功能。浏览器不支持推送时,window 上没有 PushManager,
这时隐藏订阅控件,保留已有渠道,例如站内收件箱或邮件摘要。
iOS 的 Safari 标签页也无法通过这个检测,应用添加到主屏幕后才能通过。回退文案需要告诉用户先添加到主屏幕。
export function pushSupported() { return 'serviceWorker' in navigator && 'PushManager' in window && 'Notification' in window;}2. 在点击中请求权限
链接到“2. 在点击中请求权限”一节Notification.requestPermission() 解析为 granted、denied 或 default;把 default 当作拒绝处理。
按钮文案要说明通知用途,在它的点击处理器里调用该方法。Firefox 72 拒绝非用户手势触发的请求,Safari 同样要求
直接的用户交互,而 denied 一旦给出就是最终结果,用户到浏览器设置里改动之前不会再有提示。页面加载时贸然请求权限,可能导致通知一直无法发送,
直到用户修改设置。
subscribeButton.addEventListener('click', async () => { const permission = await Notification.requestPermission(); if (permission !== 'granted') { subscribeButton.disabled = true; subscribeButton.textContent = '本站的通知已关闭'; return; } await subscribe();});3. 用 VAPID 公钥订阅
链接到“3. 用 VAPID 公钥订阅”一节在同一次用户手势中调用 pushManager.subscribe(),传入 userVisibleOnly: true 与服务端的 VAPID 公钥作为
applicationServerKey。userVisibleOnly 不为 true 时 Chrome 与 Edge 拒绝该 Promise,并且它们要求提供
这个密钥(或在 manifest 里写旧式的 gcm_sender_id)。密钥是一个 ECDSA P-256 公钥,在服务端做 Base64url
编码;它不是用来加密载荷的 ECDH 密钥。
function base64UrlToUint8Array(base64Url) { const padding = '='.repeat((4 - (base64Url.length % 4)) % 4); const base64 = (base64Url + padding).replace(/-/g, '+').replace(/_/g, '/'); return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));}
async function subscribe() { const registration = await navigator.serviceWorker.ready; const existing = await registration.pushManager.getSubscription(); const subscription = existing || (await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: base64UrlToUint8Array(VAPID_PUBLIC_KEY), })); await fetch('/api/push/subscribe', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(subscription.toJSON()), });}4. 保存订阅,并把它当作会过期的东西
链接到“4. 保存订阅,并把它当作会过期的东西”一节subscription.toJSON() 给出 endpoint 以及服务端加密与发送所需的 p256dh 与 auth 密钥。
endpoint 是指向某台设备的能力 URL,所以只在服务端保存,并为订阅接口做好 CSRF 防护。如果订阅时带了 application server key,推送服务还要求请求带有对应 VAPID 私钥的签名(RFC 8292),只拿到 endpoint 发不了消息。
每个订阅只属于一个 Service Worker 注册,推送服务可能设置过期时间,到期时 worker 会收到
pushsubscriptionchange;在那里重新订阅并更新服务器。
self.addEventListener('pushsubscriptionchange', (event) => { event.waitUntil( self.registration.pushManager .subscribe(event.oldSubscription.options) .then((subscription) => fetch('/api/push/subscribe', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(subscription.toJSON()), }), ), );});5. 在 worker 中显示通知
链接到“5. 在 worker 中显示通知”一节push 事件的 event.data 包含解密后的载荷,收到后要显示通知,履行订阅时消息对用户可见的约定。
Chrome 不限制投递配额。Firefox 会限制未显示通知的推送数量,每次访问时刷新配额。
在 notificationclick 处理器中聚焦已打开的窗口,或打开新窗口。
self.addEventListener('push', (event) => { const data = event.data ? event.data.json() : { title: '新消息', body: '' }; event.waitUntil( self.registration.showNotification(data.title, { body: data.body, icon: '/icons/icon-192.png', data: { url: data.url || '/' }, }), );});
self.addEventListener('notificationclick', (event) => { event.notification.close(); event.waitUntil( self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then((clients) => { const open = clients.find((client) => 'focus' in client); return open ? open.focus() : self.clients.openWindow(event.notification.data.url); }), );});6. 从 DevTools 发一条测试推送
链接到“6. 从 DevTools 发一条测试推送”一节写服务端代码之前,打开 Chrome DevTools,进入 Application > Service workers(英文界面),在 Push
按钮旁的输入框里填入载荷,点击 Push。worker 的 push 处理函数会带着这段文本运行;event.data.json()
遇到纯文本会抛错,所以用 {"title":"Hi","body":"test"} 来测。操作系统会弹出带你的图标的通知,
点击它会聚焦应用。随后用一个会签发 VAPID JWT、并用保存的密钥加密的 Web Push 库,从服务器发送同样的载荷。
另请参阅
链接到“另请参阅”一节- Web Push:订阅、权限与投递
- Notifications API:系统通知
- 通知权限模型
- iOS 与 Safari 的 Web Push(16.4+)
- PushManager: subscribe() method(developer.mozilla.org)
- Web Push for Web Apps on iOS and iPadOS(webkit.org)
- Notification: requestPermission() static method(developer.mozilla.org)
← 返回指南总览。