用于网页推送的 OneSignal WordPress 插件设置

概述

本指南介绍如何设置和配置 OneSignal WordPress Web Push 插件 v3+。

有关旧版本 2.x.x WordPress 文档,请参阅 WordPress 旧版插件。

版本 3+ 的新功能

此版本通过简化设置和配置过程进行了重大升级。使用版本 3+,您可以在一个地方处理所有提示设置——OneSignal 仪表板。

🚀 SDK 升级: 将 OneSignal Web SDK 从版本 15 升级到版本 16
💬 仪表板提示: 直接在 OneSignal 仪表板中配置所有权限提示——无需自定义代码
⏩ 一键发布: 勾选”发布文章时发送通知”即可自动发送推送通知
🧑‍🤝‍🧑 受众定位: 为每篇文章选择接收通知的分段
📲 移动应用集成: 通过可选的深度链接向移动应用订阅者发送通知

设置

在开始之前,请确保您具备:

OneSignal 账户(免费创建)
WordPress 管理员访问权限以安装和配置插件
启用了 HTTPS 的网站(网页推送通知所必需)

1. 在 OneSignal 仪表板中配置 WordPress

导航到 设置 > 推送和应用内 > Web > WordPress 插件或网站构建器

OneSignal 仪表板网页渠道设置,已选择 WordPress — 从 OneSignal 仪表板的网站构建器选项中选择 WordPress

网站设置

网站名称: 您的网站名称和默认通知标题。
网站 URL: 必须与您的 WordPress 网站的确切 URL 匹配(遵循同源策略)
自动重新订阅: 启用此选项可在清除浏览器数据的用户返回您的网站时自动重新订阅他们(无需新的权限提示)
默认图标 URL: 用于通知和提示的正方形 256×256 PNG、JPG 或非动画 GIF。请参阅通知图标。

OneSignal 网页渠道的网站 URL 和默认图标字段 — 输入您的确切网站 URL。https://your-site.com 与 https://www.your-site.com 不同——始终仅使用一种格式

在本地测试?请参阅本地测试指南了解 localhost 开发信息

权限提示

为推送、电子邮件和/或短信设置您的权限提示。推送滑动提示默认启用,但您可以自定义或添加其他提示。

专业提示: 从简单的提示开始,逐步增加复杂性。您可以随时通过 OneSignal 仪表板修改所有提示设置。在网页权限提示中探索所有可用选项。

基本提示设置
高级:基于类别的分段

点击推送滑动提示进行自定义

配置时间和文本:

将 自动提示 设置为 1 次页面浏览和 1 秒用于初始测试
- 自定义提示文本和外观
- 根据启动后的用户行为调整时间

滑动提示编辑器,显示自动提示延迟和文本字段 — 配置自动提示时间并自定义提示外观

配置完提示后点击完成。

要根据用户兴趣进行有针对性的消息传递,请设置类别:

在您的提示设置中选择类别

为每个类别配置:

标签: 用户在提示中看到的内容
标签键: 用于分段的内部标签键

配置完提示后点击完成。

类别提示配置,包含新闻和优惠的标签及标签键 — 示例:设置新闻和优惠类别会为勾选这些选项的用户创建标签 'news: 1' 和 'deals: 1'

标签逻辑: 勾选的类别将标签值设置为 1,未勾选的设置为 0。这些标签可实现针对特定用户兴趣的定向消息传递。

欢迎通知

设置用户首次订阅后立即发送的通知。这可以:

感谢用户订阅
演示通知的显示方式
提高参与度并减少取消订阅

配置您的欢迎消息文本和时间,然后向下滚动并点击保存。

跳过 OneSignal 仪表板中的 高级推送设置。这些字段(包括 service worker 路径)是用于典型站点或自定义代码的,而非此插件。点击保存继续。

2. 配置 WordPress 插件

保存仪表板配置后,您将看到您的 App ID 和 API Key(即 Keys & IDs 中记录的同一个 REST API 密钥)。将这些值复制到您的 WordPress 插件:

OneSignal 密钥页面,显示用于 WordPress 的 App ID 和 REST API Key — 从 OneSignal 仪表板复制您的 App ID 和 API Key

看不到 API Key? 按照我们的 Keys & IDs 指南创建一个。

在您的 WordPress 管理后台,导航到 OneSignal 插件设置

准确粘贴仪表板中显示的 App ID 和 REST API Key

WordPress OneSignal 插件设置,包含 App ID 和 REST API Key 字段 — 确保您的 WordPress 插件 App ID 和 REST API Key 与 OneSignal 仪表板完全匹配

高级设置

根据您的需求配置其他插件选项:

URL 参数跟踪 向通知 URL 添加分析参数以进行跟踪。重要: 转义特殊字符——输入内容会原样添加到 URL 中。 Google Analytics 示例:

utm_medium=push&utm_source=onesignal&utm_campaign=wordpress-plugin

包含特殊字符的示例:

utm_medium=ppc&utm_source=adwords&utm_campaign=snow%20boots&utm_content=durable%20snow%20boots

其他设置

自定义文章类型: 添加来自插件的文章类型以启用通知选项
文章发布时自动发送通知: 发布文章时自动勾选通知框,这样无需手动勾选即可发送通知
文章更新时自动发送通知: 更新文章时自动勾选通知框,这样无需手动勾选即可发送通知
页面发布时自动发送通知: 发布页面时自动勾选通知框,这样无需手动勾选即可发送通知
页面更新时自动发送通知: 更新页面时自动勾选通知框,这样无需手动勾选即可发送通知
从第三方插件发布文章时自动发送推送通知: 从外部发布插件自动发送通知
移动应用集成: 使用相同的 OneSignal App ID 向您的移动应用订阅者发送通知

Service worker

插件会为您托管并注册 service worker。您无需将 OneSignalSDKWorker.js 上传到网站根目录,也无需在仪表板或 OneSignal.init() 中设置自定义路径。版本 3+ 从插件的 sdk_files 目录提供一个纯 JavaScript 文件。它会导入 CDN worker:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

从 WordPress.org 安装时使用此 URL(文件夹名称为 onesignal-free-web-push-notifications): https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js 如果您是通过 zip 安装的,插件文件夹可能不同(例如 OneSignal-WordPress-Plugin)。请在 wp-admin 中查看插件,或在 wp-content/plugins/ 下查找,然后在路径中使用该文件夹名称。在安装了插件的情况下,请勿按照 OneSignal service worker 的根目录上传或自定义路径步骤操作。这些说明仅适用于典型站点和自定义代码。如果您需要自定义 worker 位置或对 init 的完全控制,则需要切换到自定义代码设置:请先卸载插件。这不是 WordPress 集成内的设置项。

3. 完成迁移(仅限升级用户)

新安装可以跳过此步骤。如果您从 v2+ 升级,请继续…

时间敏感: 尽快完成这些步骤以避免用户在过渡期间错过通知。

保存 OneSignal 仪表板配置后,返回 WordPress

在插件设置中点击迁移已完成

点击保存设置以完成升级

WordPress OneSignal 插件的迁移已完成复选框和保存设置 — 点击迁移已完成以完成您的插件升级

设置完成!点击 保存设置 完成插件配置。

测试您的设置

初始测试
验证订阅
发送测试消息

访问您的网站,在普通(非无痕)窗口中进行最可靠的测试。隐私浏览模式可能会显示提示,但订阅通常无法持久保存——请参阅 WordPress 故障排除。
查找您配置的滑动提示。
您配置的滑动提示应根据您的时间设置显示
点击订阅按钮(在此示例中标记为 Subscribe)。
接受浏览器权限(出现提示时)。
网页推送通知需要浏览器权限提示(外观因浏览器而异)
检查欢迎通知(如果已配置)。
成功订阅后立即显示欢迎通知

成功! 您的 WordPress 网站现已配置为网页推送通知。用户在订阅时会开始出现在您的订阅中。

下一步:

查看网页权限提示了解高级自定义
探索渠道设置以实现电子邮件和短信集成
设置分段策略以进行定向消息传递

遇到问题? 查看我们的 WordPress 故障排除指南以获取常见解决方案。

发布通知

当您安排文章发布时,OneSignal 也会安排在计划时间向您的订阅者发送推送通知。如果您重新安排文章,推送通知将被取消,并为新时间安排新的推送。您可以在 OneSignal 仪表板的 投递 > 计划消息 下查看您的计划和已取消的通知。有关更多详细信息,请参阅推送消息报告。

基本文章通知

创建或编辑 WordPress 文章时,找到 OneSignal 推送通知 元框(通常在文章编辑器的底部或侧边栏)。

WordPress 文章编辑器中的 OneSignal 推送通知元框,包含发送复选框 — OneSignal 推送通知元框——如需要可拖动重新定位

发送通知:

勾选 “文章发布或更新时发送通知”
取消勾选可跳过为该文章发送通知

受众定位

发送给所有订阅者(默认)

默认情况下,通知会发送给所有推送订阅者。

发送给特定分段

使用您在 OneSignal 仪表板 > 受众 > 分段 中创建的分段来定位特定受众。 如果您在仪表板中设置了基于类别的提示(请参阅设置下的 高级:基于类别的分段),请创建相应的分段:

在您的 OneSignal 仪表板中转到 受众 > 分段
使用您的标签键创建分段,例如:
- 新闻分段: 标签 news 为 1
- 优惠分段: 标签 deals 为 1

OneSignal 分段编辑器,包含 news 和 deals 的标签筛选器 — 标签区分大小写!'news' 和 'News' 是不同的标签

创建分段后,刷新您的 WordPress 文章编辑器
从下拉菜单中选择您的目标分段

WordPress OneSignal 元框中用于受众定位的分段下拉菜单 — 选择特定分段以定位相关用户组

高级分段: 根据用户行为、位置、设备类型等创建分段。标签为自定义用户数据和个性化提供了最大的灵活性。

自定义通知内容

默认行为

标题: 使用您的 WordPress 网站标题(设置 > 常规)
消息: 使用文章标题
图片: 使用文章的特色图片(如果已设置)
URL: 链接到已发布的文章

自定义内容

勾选 “自定义通知内容” 以覆盖默认设置:

WordPress OneSignal 元框中的自定义通知标题和消息字段 — 自定义通知标题、内容和其他元素

示例结果:

包含标题、图片和正文的自定义网页推送通知示例 — 自定义推送通知向用户显示的效果

将自定义文章类型添加到 OneSignal WordPress 插件

查找您的自定义文章类型名称

创建新文章时查看浏览器的地址栏。URL 看起来像:

https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type

post_type 参数的值(例如 your_custom_type)就是您需要在 OneSignal 插件设置中添加的确切名称。

添加到 OneSignal 设置

在 WordPress 管理后台转到 OneSignal > 设置
在 高级设置 中,将您的自定义文章类型名称添加到 自定义文章类型 字段
保存设置

常见示例: product (WooCommerce)、tribe_events (The Events Calendar)、portfolio。

移动应用集成

如果您有一个使用相同 OneSignal App ID 的移动应用:

在插件设置中启用 “向移动应用订阅者发送通知”
在文章元框中,添加用于深度链接的 移动 URL
移动用户将被引导到您的应用而不是网页浏览器

准备扩展: 探索高级推送策略和自动化旅程以实现复杂的通知活动。

通知未显示? 查看我们的网页推送故障排除指南以获取解决方案。

常见问题

我需要上传 service worker 文件吗?

不需要。WordPress 插件会在其 sdk_files 目录中托管 OneSignalSDKWorker.js 并为您配置路径。请勿将该文件上传到网站根目录,也不要在代码中设置 serviceWorkerPath。请参阅 Service worker。

如何在特定页面上禁用提示?

注意: 此方法仅适用于滑动提示和原生权限提示,不适用于铃铛或自定义链接提示。

在您的 OneSignal 仪表板中,转到 设置 > 推送和应用内 > Web 设置
从 权限提示设置 表中选择您的提示
取消勾选 自动提示 并点击完成

向下滚动,点击保存,然后点击完成
在您希望提示出现的特定页面上添加自定义 JavaScript 代码

这使您可以完全控制提示的时间和位置。有关实现详细信息,请参阅网页权限提示。

我可以向移动应用订阅者发送通知吗?

可以!如果您的移动应用使用相同的 OneSignal App ID:

在 WordPress 插件设置中启用 “向移动应用订阅者发送通知”
发布文章时,使用 OneSignal 元框中的 移动 URL 字段指定深度链接
如果没有自定义移动 URL,用户将被引导到您的网站

此功能可从单个 WordPress 界面实现跨平台消息传递。

如何从 WordPress 发送电子邮件或短信?

WordPress 插件目前仅支持推送通知。对于电子邮件和短信:

电子邮件: 按照我们的电子邮件设置指南,然后使用电子邮件消息工具
短信: 按照我们的短信设置指南,然后使用短信消息工具

这两个渠道都可以从与推送通知相同的 OneSignal 仪表板进行管理。

为什么迁移后我的提示不起作用?

缓存问题: WordPress 缓存可能会延迟迁移更改。解决方案:步骤 1: 右键点击您的网站并选择检查步骤 2: 转到网络选项卡步骤 3: 勾选 “禁用缓存”

Chrome DevTools 网络选项卡,已勾选禁用缓存 — 禁用浏览器缓存以强制在迁移后加载更新的文件

步骤 4: 刷新您的网站以查看当前配置步骤 5: 如果适用,清除您的 WordPress 缓存插件设置

`A bad HTTP response code (404)` 错误是什么意思?

此错误表示迁移不完整:

浏览器控制台显示 OneSignal 的 bad HTTP response code 404 — 浏览器控制台中的 404 错误表示迁移过程不完整

解决方案:

确保您已保存 OneSignal 仪表板配置
在 WordPress 中,在插件设置中点击 “迁移已完成”
点击 保存设置 以完成升级

此错误仅影响从版本 2.x.x 升级的用户。

我可以在发送前修改通知参数吗?

可以,您可以使用 onesignal_send_notification 过滤器。

将自定义 PHP 代码放在 wp-content/mu-plugins/onesignal-custom.php 中。这确保其正确加载并防止被更新覆盖。

<?php

add_filter('onesignal_send_notification', function ($fields, $post_id) {

  // Add fields supported by the Create notification API:
  // https://documentation.onesignal.com/reference/create-notification

  $fields['web_buttons'] = array(
    array(
      'id' => 'read-more',
      'text' => 'Read More',
      'url' => get_permalink($post_id),
    ),
  );

  return $fields;

}, 10, 2);

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

用于网页推送的 OneSignal WordPress 插件设置

概述

版本 3+ 的新功能

设置

1. 在 OneSignal 仪表板中配置 WordPress

网站设置

权限提示

欢迎通知

2. 配置 WordPress 插件

高级设置

Service worker

3. 完成迁移(仅限升级用户)

测试您的设置

发布通知

基本文章通知

受众定位

发送给所有订阅者(默认)

发送给特定分段

自定义通知内容

默认行为

自定义内容

将自定义文章类型添加到 OneSignal WordPress 插件

查找您的自定义文章类型名称

添加到 OneSignal 设置

移动应用集成

常见问题

​概述

​版本 3+ 的新功能

​设置

​1. 在 OneSignal 仪表板中配置 WordPress

​网站设置

​权限提示

​欢迎通知

​2. 配置 WordPress 插件

​高级设置

​Service worker

​3. 完成迁移(仅限升级用户)

​测试您的设置

​发布通知

​基本文章通知

​受众定位

​发送给所有订阅者(默认)

​发送给特定分段

​自定义通知内容

​默认行为

​自定义内容

​将自定义文章类型添加到 OneSignal WordPress 插件

​查找您的自定义文章类型名称

​添加到 OneSignal 设置

​移动应用集成

​常见问题

概述

版本 3+ 的新功能

设置

1. 在 OneSignal 仪表板中配置 WordPress

网站设置

权限提示

欢迎通知

2. 配置 WordPress 插件

高级设置

Service worker

3. 完成迁移(仅限升级用户)

测试您的设置

发布通知

基本文章通知

受众定位

发送给所有订阅者(默认)

发送给特定分段

自定义通知内容

默认行为

自定义内容

将自定义文章类型添加到 OneSignal WordPress 插件

查找您的自定义文章类型名称

添加到 OneSignal 设置

移动应用集成

常见问题