Web 推送配置

要开始使用 Pushwoosh 发送 Web 推送通知，您需要配置您的 Web 推送平台并启用向用户显示的订阅提示。

重要提示

请确保 Web Push SDK 已正确集成到您的网站中。这是允许用户订阅和接收通知的必要步骤。了解更多

要开始配置，请前往 Settings > Platform Configuration > Web Push Notifications 并点击 Configure。

为所有浏览器配置 Web 推送（旧版 Safari 除外）

此配置适用于所有现代浏览器，包括最新版本的 Safari，这些版本现在已原生支持 Web 推送通知。

**注意：**旧版 Safari (macOS 10.14–12) 需要单独设置。您可以在专用部分进行配置。了解更多

要开始设置，请点击 All browsers configuration 下的 Configure。

在配置窗口中，选择以下选项之一：

• Create a new push configuration 如果您之前未通过其他服务设置过 Web 推送通知，建议选择此项。Pushwoosh 将自动生成一个新的 VAPID 密钥对。

• Use existing configuration 如果您已有 VAPID 密钥（例如，来自 Firebase），并希望继续使用它们而无需再次请求用户订阅，请选择此选项。

创建新的推送配置

如果您之前未使用其他服务设置过 Web 推送通知，请选择 Create a new push configuration。Pushwoosh 将自动为您生成所需的 VAPID (Voluntary Application Server Identification) 密钥。

什么是 VAPID 密钥？

VAPID 密钥是在 Web 推送协议中使用的一对公钥-私钥，用于在向 Web 浏览器发送推送通知时验证应用服务器。当用户订阅通知时，公钥会与浏览器共享。私钥保留在您的服务器上，用于安全地签署您发送的每条消息。

点击 Configure 以生成并应用密钥。

创建后，Pushwoosh 将在 SDK 配置中自动使用这些密钥。了解有关集成 Web Push SDK 的更多信息

使用现有配置

如果您已有 VAPID 密钥（例如通过 Firebase 生成的密钥），您可以重复使用它们在 Pushwoosh 中设置 Web 推送通知。

为此：

1. 选择 Use existing configuration。
2. 在 Web Push Certificate 字段中，输入您的 VAPID 公钥。
3. 在 Web Push Private Key 字段中，输入您的 VAPID 私钥。
4. 点击 Configure 以保存并应用设置。

如何在 Firebase 中查找 VAPID 密钥

如果您正在从 Firebase 迁移并需要重用现有的 VAPID 密钥，请按照以下步骤查找它们。

Web 推送证书

1. 在 Firebase 中，导航至 Project Settings → Cloud Messaging。
2. 向下滚动到 Web Configuration 部分，并复制现有的密钥对。

3. 将其粘贴到 Pushwoosh Web 配置表单的 Web Push Certificate 字段中。

Web 推送私钥

1. 在 Firebase Console 中，前往 Project Settings → Cloud Messaging → Web Configuration。
2. 点击密钥对旁 Actions 下的三点菜单，然后选择 Show private key。此密钥对于确保 Web 推送通知正常运行至关重要。

3. 将显示的密钥复制到剪贴板。
4. 在 Pushwoosh Web Configuration 表单中，将其粘贴到 Web Push Private Key 字段中。

5. 点击 Apply 以保存您的更改。

重新配置 Web 推送配置

如果您已经设置了 Web 推送通知，但需要更新您的凭据（例如替换您的 VAPID 密钥），请按以下步骤操作：

1. 点击 All browsers configuration 下的 Reconfigure。

2. 在出现的弹出窗口中，输入您的新 VAPID 密钥：

   • Web Push Certificate：您的新 VAPID 公钥
   • Web Push Private Key：您的新 VAPID 私钥

3. 点击 Configure 以保存更改。

重要提示

替换您的 VAPID 密钥会影响您的整个 Web 推送设置，如果管理不当，可能会中断通知的发送。仅在确实必要时才更改密钥，并确保在进行任何更新前了解其影响。

配置订阅提示

要发送推送通知，用户必须通过浏览器的系统级提示明确授予权限。没有此权限，通知将无法送达。

由于最近 Chrome 和 Firefox 的政策变更，原生权限弹出窗口只能在用户与页面互动（例如，点击按钮）后出现。为满足此要求，Pushwoosh 默认会显示一个 Subscription Prompt widget (订阅提示小部件)。此小部件鼓励用户选择加入，并在用户同意后触发原生浏览器提示。

提示

一个精心设计的提示，解释通知的价值（例如，“获取最新新闻和更新”），可以显著提高选择加入率。

要自定义提示文本和外观，请点击 Settings。

提示类型

有两种可用的订阅提示类型：

• Default widget 由 Pushwoosh 提供并自动显示。了解如何自定义默认小部件。

• Custom widget 使用您自己的小部件设计。了解更多

**注意：**由于平台限制，对小部件的更改可能需要长达 30 分钟才能生效。如果更改未反映出来，请联系 Pushwoosh 支持团队。

Safari 配置 (macOS 10.14–12)

要支持旧版 Safari (macOS 10.14–12) 上的推送通知，您需要使用您的 Apple Developer 凭据完成一个单独的配置过程。此步骤仅对这些旧版本是必需的，因为新版 Safari (macOS Ventura 及更高版本) 支持包含在所有浏览器配置中的标准 Web 推送设置。

从 Apple 获取所需凭据

1. 前往 Apple Developer Portal 的 Certificates, Identifiers & Profiles 部分。
2. 添加新证书。

3. 选择 Website Push ID Certificate 类型，然后点击 Continue。

4. 选择 Website Push ID - 您的唯一反向域名字符串，例如 web.com.example.domain (必须以 web. 开头)。

5. 上传一个证书签名请求 (Certificate Signing Request)。要了解有关创建证书签名请求的更多信息，请参阅 Developer Account Help 文章。

6. 之后，下载推送通知证书。

注意

您从 Apple 下载的证书是 .cer 文件。要获取配置 Pushwoosh 所需的 .p12 文件，您必须导出一个私钥。详情请参阅 iOS 配置指南。

在 Pushwoosh 中配置 Safari

1. 点击 Safari Configuration 下的 Configure。

2. 在配置表单中填写以下字段：

网站名称	显示在推送提示中的您的网站名称。
允许的域名	允许请求通知权限的域名列表（每行一个）。
URL 模板	用户点击通知时打开的 URL。支持像 %@ 这样的占位符来插入动态值。示例：https://yourwebsite.com/%@
网站图标	上传一个方形 PNG 图片 (256×256 像素)。Pushwoosh 会自动为不同界面调整其大小。
密钥文件	上传从您的 Apple Developer 帐户导出的 .p12 证书。
私钥密码	导出 .p12 文件时使用的密码。

3. 点击 Configure 以保存您的更改。

Pushwoosh 将自动生成包含图标集、网站 JSON 字典和 Safari 从服务器请求的清单文件的推送包。您可以在需要时随时下载它。

重要提示

当用户被请求允许接收推送通知时，Safari 会向 Pushwoosh 的 Web 服务器请求一个 push package (推送包)。该包包含通知 UI 使用的数据，例如您的网站名称和图标，以及一个验证您的通知来自可信来源（即您自己）的加密签名。

包含所有内容的推送包仅在每个订阅用户注册时下载一次，并且无法在设备上强制更新。

在为您的网站在生产环境中启动 Safari 推送通知时，请考虑这一点。