Web 推送配置

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

重要提示

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

要开始配置，请前往 设置 > 平台配置 > Web 推送通知 (Settings > Platform Configuration > Web Push Notifications)，然后点击 配置 (Configure)。

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

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

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

要开始设置，请点击 所有浏览器配置 (All browsers configuration) 下的 配置 (Configure)。

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

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

• 使用现有配置 如果您已有 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 推送证书 (Web Push Certificate) 字段中，输入您的 VAPID 公钥。

3. 在 Web 推送私钥 (Web Push Private Key) 字段中，输入您的 VAPID 私钥。

4. 点击 配置 (Configure) 以保存并应用设置。

如何在 Firebase 中查找 VAPID 密钥

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

Web 推送证书

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

3. 将其粘贴到 Pushwoosh Web 配置表单的 Web 推送证书 (Web Push Certificate) 字段中。

Web 推送私钥

1. 在 Firebase 控制台中，前往 项目设置 → Cloud Messaging → Web 配置 (Project Settings → Cloud Messaging → Web Configuration)。
2. 点击密钥对旁 操作 (Actions) 下的 三点菜单，然后选择 显示私钥 (Show private key)。此密钥对于确保 Web 推送通知正常运行至关重要。

3. 将显示的密钥复制到剪贴板。

4. 在 Pushwoosh Web 配置 表单中，将其粘贴到 Web 推送私钥 (Web Push Private Key) 字段中。

5. 点击 应用 (Apply) 以保存您的更改。

重新配置 Web 推送配置

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

1. 点击 所有浏览器配置 (All browsers configuration) 下的 重新配置 (Reconfigure)。

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

   • Web 推送证书：您的新 VAPID 公钥
   • Web 推送私钥：您的新 VAPID 私钥

3. 点击 配置 (Configure) 以保存更改。

重要提示

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

配置订阅提示

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

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

提示

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

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

提示类型

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

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

• 自定义小组件 使用您自己的小组件设计。了解更多

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

Safari 配置 (macOS 10.14–12)

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

从 Apple 获取所需凭据

1. 前往 Apple Developer Portal 的 证书、标识符和描述文件部分。

2. 添加新证书。

3. 选择 网站推送 ID 证书 (Website Push ID Certificate) 类型，然后点击 继续 (Continue)。

4. 选择 网站推送 ID (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 配置 (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 推送通知时，请考虑这一点。