Demystifying Web Push Notifications

May 29, 2024

翻译自：https://pqvst.com/2023/11/21/web-push-notifications/
另见：https://web.dev/articles/push-notifications-web-push-protocol

对于我最近的 One Day Build: Expense Tracking 项目，我希望在渐进式 Web 应用中启用通知。ChatGPT 难以生成任何有用的代码，我也很难在网上找到任何简洁明了的解释。

本博客文章旨在全面介绍实现 Web Push 通知所需的所有步骤。我还创建了一个完整的工作示例，其中包含一个 node.js 后端，供那些只想查看代码而不是阅读本文的人参考：

https://github.com/pqvst/minimal-web-push

Web Push 如何运作？

简而言之，Web Push 的运作方式是，你的应用会与浏览器供应商提供的“推送服务”进行交互。此过程包含三个主要步骤，如下图所示：

web push overview

1. 创建订阅

你的客户端代码创建一个 Web Push 订阅，并将订阅发送到你的后端。订阅只是一些 JSON，其中包含唯一的（特定于浏览器的）端点和一些加密密钥。以下是 Firefox 订阅示例（因此端点是 mozilla.com）：

json

{
    "endpoint": "https://updates.push.services.mozilla.com/wpush/v2/...",
    "expirationTime": null,
    "keys": {
        "auth": "...",
        "p256dh": "..."
    }
}

使用 Safari，你将收到 Apple 端点 (https://web.push.apple.com/...)，在 Chrome 中，你将获得 Google 端点 (https://fcm.googleapis.com/fcm/send/...)。

2. 发送通知

你的后端代码使用订阅详细信息向浏览器供应商托管的推送服务发送推送通知。然后，推送服务确保将通知发送回你的浏览器。

3. 处理通知

你的浏览器收到推送通知并触发你 Service Worker 中的回调。然后，你的 Service Worker 可选择显示通知或执行你希望执行的任何其他操作。

先决条件：VAPID 密钥

VAPID 密钥对于确保 Web Push 在所有主流浏览器上正常运行是必需的。VAPID 代表 Voluntary Application Server Identification (VAPID) ，本质上只是如何生成一组公钥-私钥的规范。尽管名称中带有“自愿”，但事实并非如此，*因为 Chrome 和 Safari 都要求你提供 VAPID 密钥。*我测试过的唯一不需要 VAPID 密钥的浏览器是 Firefox。

如果你尝试在没有 VAPID 密钥的情况下在 Safari 中订阅推送通知，你将收到以下错误：

Subscribing for push requires an applicationServerKey

在 Chrome 中，你将收到此错误：

DOMException: Registration failed - missing applicationServerKey, and gcm_sender_id not found in manifest

虽然你可以在技术上自己生成 VAPID 密钥，但使用生成器（如 vapidkeys.com）要容易得多，该生成器会为你生成一组密钥。

服务端实现

为了从你的后端应用程序服务器发送 Web Push 通知，你必须正确构造、编码和加密消息。根据你使用的编程语言，你可能会找到一个可以帮助你完成此操作的库。

如果你使用 node.js 后端，那么添加 Web Push 支持非常简单。有一个很好的库叫做 web-push ，它可以为你定制 Web Push 通知。

1. 导入并配置 web-push

要开始使用 web-push，只需调用该函数来设置你的 VAPID 密钥。务必同时包含一个电子邮件地址（用 mailto: 开头）。

import webPush from "web-push";

// TODO: 生成 VAPID 密钥 (如：https://vapidkeys.com/)
const vapid = {
    publicKey: "...",
    privateKey: "...",
};

webPush.setVapidDetails("mailto:<email-address>", vapid.publicKey, vapid.privateKey);

2. 存储订阅

Web Push 订阅是在客户端生成的，因此你很可能需要某种方式将订阅从前端传递到后端。你可能还想以某种方式保存它们，例如将它们存储在你的数据库中或将它们保存在持久化 JSON 文件中。如果你不保存订阅数据，那么在你的服务器重新启动时，你将丢失所有现有的订阅！

app.post("/subscribe", authenticateRequest, (req, res) => {
    const sub = req.body;
    // TODO: 持久化订阅 (如：存入数据库)
    res.status(200).end();
});

广播通知

你只需要实现的另一件事就是实际创建和发送新通知的方式。如果我们向所有订阅广播通知，那么我们只需遍历我们保存的订阅数组并使用 web-push 库调用 sendNotification。

如果你收到错误，表示用户已撤销你的页面上通知权限（或订阅已过期）。你可以捕获这些错误并删除无效订阅。

async function pushNotification(payload) {
    await Promise.all(
        subscriptions.map(async (sub) => {
            try {
                await webPush.sendNotification(sub, payload); // 不成功会抛出异常
            } catch (err) {
                console.log(sub.endpoint, "->", err.message);
                // TODO: 删除订阅 (如：从数据库中)
            }
        }),
    );
}

// 发送测试通知
pushNotification("This is a test notification!");

客户端

客户端实现稍微复杂一些。你需要两个文件：一个用于你的 Service Worker，另一个用于你的主客户端应用程序。我们只需要将 Service Worker 的回调用于传入通知的处理。

Service Worker： `/sw.js`

self.addEventListener("push", (event) => {
    const options = {
        body: event.data.text(),
        icon: "/apple-touch-icon.png",
        badge: "/badge.png",
    };
    event.waitUntil(self.registration.showNotification("My App", options));
});

**为什么我们将我们的调用包装在 event.waitUntil 中？**由于 Service Worker 作为后台进程运行，因此可能被暂停/终止。通过将 promise 包装在 waitUntil 中，我们告诉浏览器工作正在进行中，并且它不应该在工作完成之前终止我们的 Service Worker。

客户端应用程序： `/client.js`

在我们的主应用程序脚本中，我们必须负责请求通知权限、注册我们的 Service Worker 以及使用浏览器的 pushManager API 实际创建推送通知订阅。

1. 请求通知权限

首先，我们需要注意已确保我们有权推送通知（如果没有这些权限，我们的通知毫无用处）。在你页面的某个位置，你可能会希望显示一个链接或按钮，供用户单击以启用通知。

html

<a id="promptLink" onclick="onPromptClick()">启用通知</a>

如果已授予（或拒绝）通知，我们可以隐藏链接或相应地更新 UI。

function updatePrompt() {
    if ("Notification" in window) {
        if (Notification.permission === "granted" || Notification.permission === "denied") {
            promptLink.style.display = "none";
        } else {
            promptLink.style.display = "block";
        }
    }
}

function onPromptClick() {
    if ("Notification" in window) {
        Notification.requestPermission().then((permission) => {
            updatePrompt();
            if (permission === "granted") {
                console.log("Notification permission granted.");
                init();
            } else if (permission === "denied") {
                console.warn("Notification permission denied.");
            }
        });
    }
}

2. 注册Service Worker并启用推送通知

接下来，我们确保支持 Service Worker 并注册我们的 Service Worker，以便我们可以接收通知。最后，我们将使用浏览器 pushManager API 请求推送通知订阅，然后将其发送到我们的后端服务器。

对于此步骤，你需要你的 VAPID 公钥（确保只在客户端代码中包含你的公钥，并将你的私钥保密）。

这个过程不言自明。确保支持 Service Worker，注册 Service Worker，然后检查我们是否已经拥有有效的推送通知订阅，否则创建新的订阅。

在两种情况下，我们都会将订阅数据发送到我们的后端以确保它被存储。

const vapidPublicKey = "...";

async function initServiceWorker() {
    if ("serviceWorker" in navigator) {
        const swRegistration = await navigator.serviceWorker.register("sw.js");
        const subscription = await swRegistration.pushManager.getSubscription();
        if (subscription) {
            console.log("用户已订阅：", subscription);
            sendSubscriptionToServer(subscription);
        } else {
            const subscription = await swRegistration.pushManager.subscribe({
                userVisibleOnly: true,
                applicationServerKey: vapidPublicKey,
            });
            console.log("用户已订阅：", subscription);
            sendSubscriptionToServer(subscription);
        }
    } else {
        console.warn("不支持 Service Worker");
    }
}

function sendSubscriptionToServer(subscription) {
    fetch("/subscribe", {
        method: "post",
        body: JSON.stringify(subscription),
        headers: { "content-type": "application/json" },
    });
}

window.addEventListener("load", () => {
    initServiceWorker();
    updatePrompt();
});

调试提示：重新加载 Service Worker

请注意，Service Worker 在你重新加载页面时不会自动重新加载。如果你在本地进行开发并对 Service Worker 进行修改，你需要在浏览器的开发工具中手动重新加载 Service Worker 或者启用页面重新加载时自动重新加载 Service Worker 的选项。

额外功能：可点击的通知

另一个你可能想要实现的功能是使你的通知可点击。起初，我以为点击通知会自动打开相关页面。然而，事实并非如此。你需要在你的 Service Worker 中自己实现这一功能。

实现这个功能的代码比我预想的要复杂一些。以下是我在线上找到的最佳示例，它确保在点击通知后清除通知，并且如果目标页面已经打开，则聚焦该页面，否则在新窗口/标签页中打开目标页面。

const targetUrl = "...";

self.addEventListener("notificationclick", (event) => {
    self.console.log("notificationclick");
    event.notification.close(); // Android 需要显式关闭
    event.waitUntil(
        clients.matchAll({ type: "window" }).then((windowClients) => {
            // 检查是否已经有一个窗口/标签页打开了目标 URL
            for (var i = 0; i < windowClients.length; i++) {
                var client = windowClients[i];
                // 如果是，则聚焦它
                if (client.url === targetUrl && "focus" in client) {
                    return client.focus();
                }
            }
            // 如果没有，则在新窗口/标签页中打开目标 URL
            if (clients.openWindow) {
                return clients.openWindow(targetUrl);
            }
        }),
    );
});