如何为 WordPress 设置 Webpushr 推送通知

Webpushr 是一个网页推送通知平台，即使用户已完全离开您的网站，也能向已订阅的用户实时推送浏览器通知。与电子邮件或短信不同，网页推送无需任何个人联系信息——订阅者通过 Web Push 协议和 Push API 直接经由浏览器的原生通知系统接收通知。

本指南将完整介绍整个设置流程：从账户创建和 WordPress 插件配置，到高级分段、基于触发器的自动化以及订阅者分析。同时还涵盖大多数教程完全忽略的技术边缘案例——Service Worker 冲突、HTTPS 要求、iOS 兼容性差距以及性能注意事项。

开始前的准备工作

在进入 WordPress 后台之前，请确认您的环境满足以下硬性要求：

• HTTPS 是必须的。 Push API 和 Service Worker 仅限于安全来源使用。运行在普通 HTTP 上的网站无法注册 Service Worker，因此无法推送网页通知。如果您的网站尚未启用安全连接，则需要有效的 SSL 证书——AlexHost 提供可满足此要求的 SSL 证书。
• 建议使用 WordPress 5.0 或更高版本，以确保与 Webpushr 元框完全兼容 Gutenberg 块编辑器。
• 服务器端需要 PHP 7.4 或更高版本，以避免已弃用的函数警告悄无声息地破坏插件初始化。
• 浏览器支持情况： 桌面端和 Android 上的 Chrome、Firefox 和 Edge 支持 Web Push 协议。macOS 上的 Safari 从 Safari 16（macOS Ventura）开始添加了支持。iOS Safari 在 iOS 16.4 中为添加到主屏幕的 PWA 提供了有限支持——截至本文撰写时，iOS 上基于标准浏览器的网页推送仍不可靠。
• 无冲突的 Service Worker。 如果您已运行 PWA 插件或其他推送通知服务，其 Service Worker 可能与 Webpushr 的产生冲突。请在继续操作前通过 chrome://serviceworker-internals/ 审查您当前活跃的 Service Worker。

第一步：创建并配置您的 Webpushr 账户

访问 webpushr.com 并注册新账户。在引导流程中，系统会要求您输入网站域名。请输入与浏览器地址栏中完全一致的域名，包括 www 前缀或其缺失——此值用于限定 Service Worker 的作用域，不匹配将导致订阅失败。

注册后，Webpushr 将提供两个关键凭据：

• API Key——WordPress 插件用于验证发送通知的 REST API 调用。
• Auth Token——如果您后续构建自定义集成，用于服务器端 API 请求。

在 Webpushr 后台的 Account > API Keys 下找到这两个值并妥善保存。API Key 在传统意义上并非机密（它嵌入在客户端请求中），但 Auth Token 必须保密。

Webpushr 免费版与付费版限制对比

对于大多数小型 WordPress 网站，免费版已足够在承诺付费计划之前验证该渠道的效果。

第二步：安装 Webpushr WordPress 插件

登录您的 WordPress 管理后台，按以下路径操作：

1. 前往 插件 > 安装插件。
2. 搜索 Webpushr。
3. 找到由 Webpushr Inc. 发布的官方插件——请核实发布者名称，以免安装同名插件。
4. 点击立即安装，然后点击启用。

如果您通过命令行管理 WordPress，也可以使用 WP-CLI 安装：

wp plugin install webpushr-web-push-notifications --activate

启用后，WordPress 左侧导航栏中将出现新的 Webpushr 菜单项。

插件在服务器层面的实际作用

了解插件的架构有助于您智能地排查问题。插件启用后将执行以下操作：

1. 注册重写规则，从网站根目录提供 Service Worker 文件（webpushr-sw.js）。这一点至关重要——Service Worker 必须从根作用域提供，才能控制整个来源。
2. 通过 wp_enqueue_scripts 向每个前端页面注入 JavaScript 代码片段，用于加载 Webpushr SDK 并注册 Service Worker。
3. 挂载到 publish_post 和 publish_page WordPress 动作钩子，以便在内容发布时触发自动推送通知。

如果您的缓存插件对 Service Worker 文件进行了强制缓存，订阅者可能会收到过时的推送内容，或完全无法完成注册。请将 webpushr-sw.js 从缓存规则中排除。

第三步：将插件连接到您的 Webpushr 账户

在 WordPress 后台中，前往 Webpushr > 设置。您将看到一个标有 API Key 的字段。将您在第一步中从 Webpushr 后台获取的 API Key 粘贴进去。

点击保存更改。插件将向 Webpushr API 发起验证请求。如果密钥有效，将显示成功确认信息。如果出现错误：

• 确认粘贴的密钥前后没有多余的空格字符。
• 验证您的服务器能否向 api.webpushr.com 发起出站 HTTPS 请求。某些经过加固的 VPS 配置默认会阻止出站连接。在 Linux 服务器上，可使用以下命令测试：

curl -I https://api.webpushr.com

收到 200 OK 或 301 响应即表示连接正常。如果连接超时，请使用 iptables -L OUTPUT 检查防火墙规则，或联系您的托管服务商检查网络 ACL。

如果您在 VPS 托管环境中运行 WordPress，您可以完全控制防火墙规则，并可直接将 Webpushr API 端点加入白名单。

第四步：配置订阅提示

订阅提示是浏览器权限对话框，用于询问用户是否允许接收通知。浏览器的原生权限对话框无法自定义样式——它由浏览器本身渲染。但 Webpushr 提供了一个预权限提示（在原生对话框出现之前显示的自定义覆盖层），您可以对其进行完全自定义。

在 Webpushr 后台的 Settings > Opt-in Prompt 中配置预权限提示：

• 提示样式： 可选择铃铛小部件、顶部栏、滑入框或自定义模态框。
• 提示文案： 撰写能清晰传达订阅价值的文字。模糊的提示（如”允许通知？”）的效果始终不如明确说明订阅内容的提示，例如”立即订阅，第一时间获取我们发布的最新安全公告。”
• 提示延迟： 设置显示提示前的延迟时间（以秒或页面浏览次数为单位）。页面加载后立即显示的订阅率低于用户至少浏览过一篇内容后再显示的情况。
• 重新提示间隔： 定义对已关闭提示的用户再次显示提示前需等待的天数。过于频繁的重新提示会损害用户体验并提高跳出率。

不同提示类型的订阅率基准

情境化提示——在用户完成有意义的操作（如将文章读到末尾）后显示——的效果始终优于所有其他方式。

第五步：配置通知推送设置

发布文章时自动推送

在 Webpushr > 设置中，自动推送通知开关控制每次发布文章时是否自动触发推送通知。启用后，Webpushr 会自动提取文章标题、摘要和特色图片 URL 来构建通知内容。

边缘案例： 如果您使用从预发布环境迁移到生产环境的工作流，且文章是通过程序化方式导入或更改状态的（例如通过 WP-CLI 或迁移脚本），publish_post 钩子将对每篇导入的文章触发，可能在数秒内向订阅者发送数十条通知。请在执行批量导入前禁用自动推送：

wp option update webpushr_auto_push 0

导入完成后重新启用。

在文章编辑器中手动推送

如需精细控制，可全局禁用自动推送，并使用文章编辑器中的 Webpushr 元框进行逐篇设置。该元框显示在主内容编辑器下方，提供以下控制选项：

• 发送推送通知： 勾选后，将在发布或更新时将通知加入队列。
• 自定义通知标题： 用更具吸引力的标题覆盖文章标题。
• 自定义通知内容： 覆盖自动生成的摘要。
• 自定义通知 URL： 将订阅者重定向到特定落地页，而非文章固定链接——适用于推广活动。
• 自定义通知图标： 用特定活动图片覆盖默认网站图标。

通知内容结构

网页推送通知内容由以下部分组成：

• title——以粗体显示在通知顶部。
• body——标题下方的描述性文字。
• icon——通知旁边显示的方形图片（建议尺寸 192×192 px）。
• image——在支持的平台（Android 上的 Chrome、Windows 上的 Chrome）上显示在正文下方的大横幅图片。
• badge——显示在 Android 状态栏中的小型单色图标。
• url——用户点击通知时跳转的目标 URL。
• actions——最多两个带有自定义标签和 URL 的操作按钮（Chrome 和 Edge 支持）。

将 title 控制在 50 个字符以内，将 body 控制在 120 个字符以内，可防止在大多数平台上出现截断。

第六步：端到端测试推送通知

在您登录 WordPress 的同一浏览器会话中进行测试，无法准确反映订阅者的实际体验。请使用独立的浏览器配置文件或无痕窗口：

1. 在隐私/无痕窗口中打开您的网站。
2. 预权限提示应在您配置的延迟时间后出现。
3. 点击提示中的行动号召按钮，然后在浏览器的原生权限对话框中点击允许。
4. 返回 WordPress 后台，发布一篇测试文章，或使用 Webpushr 后台中的发送测试通知按钮。
5. 验证通知是否以正确的标题、正文和图标显示，并确认点击后跳转到正确的 URL。

测试中常见的失败情况：

• 通知未显示： 检查浏览器通知是否在操作系统层面被屏蔽（Windows 专注助手、macOS 勿扰模式、Android 通知渠道）。
• Service Worker 未注册： 打开开发者工具 > 应用程序 > Service Workers，确认 webpushr-sw.js 显示为活跃状态。如果显示为”等待中”，说明另一个 Service Worker 正在阻止其激活。
• 图标无法加载： 图标 URL 必须是绝对路径（以 https:// 开头），且如果图片托管在 CDN 上，必须以宽松的 CORS 头提供服务。

第七步：高级功能——分段、定时发送与触发器

受众分段

Webpushr 的分段引擎允许您根据以下条件为订阅者打标签：

• 基于 URL 的分段： 自动为访问特定 URL 或 URL 模式的订阅者打标签（例如，所有访问 /category/security/ 的用户将被标记为 security-readers）。
• 自定义属性： 通过 JavaScript SDK 传递任意键值对，基于您的应用程序已跟踪的用户属性构建分段。
• 参与度分段： Webpushr 自动跟踪最后活跃时间戳，允许您针对 30 天以上未收到通知的订阅者创建重新激活活动。

分段功能需要付费计划，可在 Webpushr 后台的 Segments 下进行配置。

定时通知

定时发送功能允许您现在撰写通知，并在未来的指定日期和时间推送，支持时区设置。此功能在以下场景中尤为有价值：

• 有明确截止时间的限时促销活动。
• 在非流量高峰时段发布的内容，希望在高参与度时间窗口内推送。
• 定期摘要通知（例如每周精选）。

自定义触发器通知

自定义触发器根据网站上的 JavaScript 事件触发通知。例如，您可以在用户放弃购物车 24 小时后触发通知，或在用户滚动到特定深度时触发。触发器通过 Webpushr JavaScript SDK 配置，需要在 WordPress 插件默认功能之外进行自定义开发。

通知文案 A/B 测试

在付费计划中，Webpushr 支持在订阅者分段中对通知标题和正文进行分组测试。在全面推广活动前，通过 A/B 测试确定哪种文案能带来更高的点击率。

第八步：监控订阅者分析数据

Webpushr 后台提供以下指标：

• 总订阅者数： 活跃、已取消订阅和已过期的端点数量。
• 送达率： 已发送通知中成功送达浏览器推送服务（Chrome/Edge 使用 FCM，Firefox 使用 Mozilla Autopush）的百分比。
• 点击率（CTR）： 已送达通知中产生点击的百分比。
• 订阅增长趋势： 每日和每周的订阅者获取趋势。

关于”已送达”与”已接收”的重要技术说明： 当浏览器推送服务（如 Google 的 FCM）接受通知内容时，该通知即被标记为已送达。如果用户设备处于离线状态，FCM 会将通知加入队列，并在设备重新联网时推送——但仅在您配置的 TTL（生存时间）窗口内有效。默认 TTL 为 28 天。对于时效性强的通知，请设置较短的 TTL，以避免推送过时内容。

平台与浏览器兼容性矩阵

“完全支持”表示 Web Push 协议、Service Worker 和通知操作按钮均受支持。在标准浏览器会话中使用 iOS 的用户仍无法接收网页推送，这对移动端流量较大的网站而言是一个不可忽视的受众缺口。

托管基础设施注意事项

网页推送通知的推送主要由第三方推送服务（FCM、Mozilla Autopush）处理，因此您服务器的原始吞吐量不会成为推送的瓶颈。但您的托管环境会影响以下方面：

• Service Worker 文件加载速度： webpushr-sw.js 文件必须在每次页面加载时被快速获取，以便浏览器验证 Service Worker 是否为最新版本。服务器响应慢会增加该文件的首字节时间（TTFB）。
• API 响应时间： 每次发布新文章时，插件都会向 Webpushr 发起同步 API 调用。在出站连接受限的共享托管环境中，此调用可能超时并静默失败。
• Webhook 可靠性： 如果您配置了 Webpushr Webhook 以接收订阅事件通知，您的服务器必须能够可靠地接受入站 POST 请求。

在带 cPanel 的 VPS 上运行 WordPress，您可以调整 PHP 执行超时、配置出站防火墙规则，并在不受共享环境限制的情况下监控 Service Worker 推送情况。对于推送通知活动会带来大量并发流量峰值的高流量网站，独立服务器可确保您的源站能够承受由此产生的点击流量，而不会出现限速。

对于管理多个 WordPress 站点的团队，将电子邮件托管与 Webpushr 结合使用，可构建双渠道重新激活策略——推送通知追求即时性，电子邮件追求深度。

技术决策矩阵：何时选择 Webpushr 而非其他方案

Webpushr 的免费版比 OneSignal 更受限，但其 Service Worker 实现明显更简洁，与其他 WordPress 插件发生冲突的概率更低——这在复杂的 WordPress 安装环境中是一个实际优势。

上线前实用检查清单

• HTTPS 已启用，SSL 证书有效且非自签名。
• Service Worker webpushr-sw.js 可通过 https://yourdomain.com/webpushr-sw.js 访问，并返回 200 状态码。
• Service Worker 文件已从缓存插件的缓存规则中排除。
• 订阅提示延迟设置为至少 5 秒或一次页面浏览。
• 如需执行批量导入或内容迁移，已禁用自动推送。
• 已在全新浏览器会话中完成端到端测试通知接收验证。
• 通知图标尺寸为 192×192 px，且 URL 为绝对 HTTPS 路径。
• 已根据内容的时效性合理配置 TTL。
• 在首次活动前已记录分析基准数据，以便进行有意义的对比。
• 已更新 GDPR/隐私政策，披露推送通知数据收集情况。

常见问题

Webpushr 在没有 HTTPS 的情况下能正常工作吗？

不能。根据浏览器规范，Web Push API 和 Service Worker 仅限于安全来源使用。任何运行在 HTTP 上的网站都无法注册 Service Worker，因此无法发送或接收网页推送通知。SSL 证书是硬性技术要求，而非可选的最佳实践。

为什么我的推送通知无法送达部分订阅者？

最常见的原因包括：订阅者设备离线时间超过了通知的 TTL 窗口；用户在浏览器或操作系统层面撤销了通知权限；或者浏览器推送服务端点（FCM、Mozilla Autopush）返回了已过期或无效的注册信息。Webpushr 后台会将这些情况标记为”推送失败”，并自动移除返回 410 Gone 响应的端点，这符合 Web Push 协议规范的正确处理方式。

我可以向 iOS 用户发送推送通知吗？

从 iOS 16.4 起，网页推送仅支持已添加到主屏幕的渐进式 Web 应用（PWA）。在 Safari 或任何其他 iOS 浏览器中浏览您网站但未将其添加到主屏幕的用户将无法接收网页推送通知。这是 Apple 在平台层面施加的限制，并非 Webpushr 本身的局限。

Webpushr 的 Service Worker 会与我现有的 PWA 或缓存插件冲突吗？

有可能。同一时间只有一个 Service Worker 能控制给定的作用域。如果 PWA 插件（如 Super PWA）或其他推送服务已在根作用域注册了 Service Worker，Webpushr 的 Service Worker 将进入”等待”状态并永远无法激活。解决方法是使用一个同时导入两个脚本的 Service Worker，或选择单一推送服务提供商并禁用其他服务。请通过 chrome://serviceworker-internals/ 审查您域名上所有已注册的 Service Worker。

禁用 Webpushr 插件会取消现有订阅者的订阅吗？

不会。停用插件会从前端移除 JavaScript SDK，从而阻止新订阅并停止自动通知。但现有的推送端点注册在浏览器中仍然有效，直到用户主动撤销权限或端点过期。如果您使用相同的 API Key 重新启用插件，这些订阅者将立即可以再次接收通知。