WordPress 旧版设置

这份综合指南将带您了解如何使用 OneSignal WordPress 插件版本 2.x.x 设置和自定义网页推送通知。如果您使用的是版本 3 或更高版本，请参阅我们的 WordPress v3+ 指南。

本指南专针 OneSignal WordPress 插件版本 2.x.x。对于版本 3+，请参阅我们更新的 WordPress 文档。

前置条件

具有管理员访问权限的 WordPress 网站
已启用 HTTPS（网页推送通知所需）
OneSignal 账户（在 onesignal.com 免费获取）

步骤 1：选择集成

在 onesignal.com 创建您的 OneSignal 账户。如果这不是您的第一个应用，选择新应用/网站，为您的应用命名，选择网页，然后点击“下一步”。

平台选择界面显示网页选项

选择 WordPress 插件或网站构建器继续：

网页推送集成选项，突出显示 WordPress 插件

步骤 2：站点设置

仔细配置您的站点信息，因为这些设置会影响所有通知：

站点设置配置表单及必填字段

字段	描述	要求
站点名称	在推送通知中显示的默认名称	保持简洁以获得更好显示效果
站点 URL	您的完整网站 URL	必须包含 `http://` 或 `https://` 并与您的实际 URL 格式匹配
自动重新订阅	自动为返回的用户重新订阅（仅限 HTTPS）	推荐 - 减少清除浏览器数据用户的阻力
默认图标 URL	用于提示和通知的图标	必须为 HTTPS，正方形 256x256 像素，PNG/JPG/GIF 格式

**URL 格式重要提醒：**确保您的站点 URL 与用户访问您站点的方式完全匹配。URL 不匹配（www 与 non-www，http 与 https）可能会导致订阅问题。

步骤 3：高级推送设置（可选）

OneSignal 免费提供 Safari 网页推送证书。只有在您有特定需求时才上传自定义证书。

高级推送设置显示 Safari 证书上传选项

何时使用自定义证书：

您已有现有的 Safari 证书
您的组织需要特定的证书管理
您需要自定义证书品牌

步骤 4：配置 WordPress 插件

安装插件

从您的 WordPress 管理员界面或通过在插件目录中搜索“OneSignal”来添加 OneSignal WordPress 插件。

配置 API 密钥

从 OneSignal 仪表板复制您的 App ID 和 API 密钥：

OneSignal 仪表板显示 App ID 和 API 密钥位置

导航到您的 WordPress 管理员 → OneSignal Push → 配置选项卡并粘贴密钥：

WordPress 插件配置显示 API 密钥输入字段

启用推送提示

激活滑动提示和订阅铃铛以向访问者请求权限：

提示设置显示滑动提示和订阅铃铛选项

保存您的配置 - 这对于插件正常工作至关重要。

配置页面底部的保存按钮位置

步骤 5：测试您的设置

验证安装

访问您的网站（您可能需要清理缓存插件）
寻找 OneSignal 滑动提示和订阅铃铛
订阅以测试流程
检查 OneSignal 仪表板 → 受众 → 用户 以确认您的订阅

发送测试通知

导航到 OneSignal 仪表板 → 消息 → 新推送 以发送您的第一个通知并验证一切正常工作。

**故障排除：**如果提示未出现，请检查推送通知是否在您的设备设置中启用，并尝试清理您的浏览器缓存。

步骤 6：配置通知提示

在配置部分设置用户如何以及何时看到订阅提示：

订阅铃铛

一个永久图标（通常在角落），用户可以随时点击来管理他们的订阅状态。

滑动提示

一个根据您的时间设置出现的模态对话框，用于请求权限。 **后续步骤：**用户通常希望自定义提示时间和外观。请参见下面的高级自定义部分。

步骤 7：自动文章通知

基本设置

创建文章时，您将看到一个 OneSignal 部分。勾选 发布文章时发送通知 来通知订阅者：

文章编辑器显示 OneSignal 通知复选框

自动启用通知

为所有新文章自动勾选此框：

转到 OneSignal Push → 自动通知设置
启用 创建文章时自动发送推送通知
保存设置

自动通知设置显示自动发送选项

欢迎通知

配置在用户订阅后立即发送的可选欢迎消息。在您插件的配置部分编辑或禁用它们。

**速率限制：**同一文章的多个通知仅限为每分钟一个，以防止垃圾邮件。

高级自定义

OneSignal WordPress 插件使用您配置的选项加载我们的网页推送 SDK。您可以使用任何网页推送 SDK JavaScript APIs 来进一步自定义体验。

**开发者注释：**此部分需要 JavaScript 和 PHP 知识。如果您需要帮助将代码添加到您的站点，请考虑使用 Insert Headers and Footers 或 Custom CSS & JS 等插件。

自定义订阅提示

Advanced Prompt Setup

对于包括延迟、分类和邮件收集的复杂提示自定义：

步骤 1：禁用默认提示

在 OneSignal WordPress 插件 → 提示设置 中，关闭滑动和原生提示（您可以保持铃铛启用）。

提示设置显示已禁用的滑动和原生提示

步骤 2：启用手动初始化

滚动到 高级设置 并打开“禁用 OneSignal 初始化”，然后保存。

高级设置显示手动初始化开关

步骤 3：添加自定义 JavaScript

将此代码添加到您的站点（在示例中显示的 3 秒延迟之后）：

// 基本延迟提示
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "push",
          autoPrompt: true,
          text: {
            actionMessage: "获取新文章和更新通知！",
            acceptButton: "是",
            cancelButton: "不，谢谢",
          },
          delay: {
            timeDelay: 10, // 等待 10 秒
            pageViews: 2,  // 在 2 次页面浏览后显示
          }
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);

// 基于分类的提示
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "category",
          autoPrompt: true,
          text: {
            actionMessage: "选择您希望接收的通知类型：",
            acceptButtonText: "订阅",
            cancelButtonText: "不是现在",
            positiveUpdateButton: "保存偏好设置",
            negativeUpdateButton: "取消",
            updateMessage: "更新您的通知偏好设置。",
          },
          categories: [
            {
              tag: "news",
              label: "突发新闻",
            },
            {
              tag: "sports",
              label: "体育更新",
            },
            {
              tag: "tech",
              label: "技术新闻",
            }
          ]
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);

页面特定提示

服务器端 PHP 方法

使用 onesignal_initialize_sdk 过滤器来根据页面属性控制初始化。

客户端 JavaScript 方法

启用“禁用 OneSignal 初始化”并添加条件 JavaScript 以仅在特定页面上初始化 OneSignal。

多语言提示

对于单语言站点，只需在提示配置中翻译文本即可。对于多语言站点，使用上面的手动初始化方法并检测页面语言以显示适当的文本。

用户分段与定向

标记用户

使用数据标签对用户进行分类，以发送有针对性的通知：

// 根据用户的兴趣标记用户
OneSignal.push(function() {
  OneSignal.sendTag("interest", "technology");
  OneSignal.sendTag("location", "california");
});

定向细分市场

在您的 OneSignal 仪表板中使用 用户标签 过滤器创建细分市场，然后使用 onesignal_send_notification 过滤器对其进行定向：

<?php
add_filter('onesignal_send_notification', 'target_tech_users', 10, 4);

function target_tech_users($fields, $new_status, $old_status, $post) {
  // 仅发送给对技术感兴趣的用户
  $fields['included_segments'] = array('Technology Enthusiasts');
  return $fields;
}

通知中的特色图片

启用特色图片支持

确保您的主题支持特色图片。检查您主题的 functions.php 中是否有：

add_theme_support('post-thumbnails');

配置图片设置

在 OneSignal Push → 已发送通知设置 中，打开所需的特色图片选项：

特色图片设置显示图标和大图片选项

第三方插件集成

标准文章类型

为标准文章类型启用 从第三方插件发布文章时自动发送推送通知。

第三方插件集成设置

自定义文章类型

在“附加自定义文章类型”字段中添加自定义文章类型（逗号分隔）：

自定义文章类型配置字段

查找自定义文章类型： 创建自定义文章类型时查看您浏览器的 URL： https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type post_type 参数显示要添加的名称。

移动应用集成

方法 1：简单的网页浏览器打开

在您的 WordPress 插件设置中启用 额外向 iOS 和 Android 平台发送通知。

移动平台集成开关

方法 2：深度链接

对于自定义移动应用行为，禁用上述设置并使用此 PHP 代码：

<?php
add_filter('onesignal_send_notification', 'send_to_mobile_apps', 10, 4);

function send_to_mobile_apps($fields, $new_status, $old_status, $post) {
  $fields['isAndroid'] = true;
  $fields['isIos'] = true;
  $fields['isAnyWeb'] = true;
  $fields['data'] = array("customkey" => $fields['url']);
  $fields['web_url'] = $fields['url'];
  unset($fields['url']); // 防止在移动设备上打开浏览器

  return $fields;
}

WordPress 插件钩子和过滤器

代码放置

将自定义 PHP 代码放置在 wp-content/mu-plugins/ 中以防止被更新覆盖。

创建 wp-content/mu-plugins/onesignal-custom.php 并加入您的自定义代码。

onesignal_send_notification

在发送之前修改通知参数：

<?php
add_filter('onesignal_send_notification', 'customize_notification', 10, 4);

function customize_notification($fields, $new_status, $old_status, $post) {
  // 自定义标题和消息
  $fields['headings'] = array("zh" => "突发新闻！");
  $fields['contents'] = array("zh" => "查看我们的最新文章");

  // 安排在稍后发送
  $fields['send_after'] = "2024-12-25 09:00:00 GMT-0800";

  // 添加操作按钮
  $fields['web_buttons'] = array(
    array(
      "id" => "read-more",
      "text" => "阅读更多",
      "url" => get_permalink($post->ID)
    )
  );

  return $fields;
}

onesignal_initialize_sdk

控制 OneSignal 何时初始化：

<?php
add_filter('onesignal_initialize_sdk', 'control_initialization', 10, 1);

function control_initialization($settings) {
  // 仅在博客文章上初始化
  if (is_single() && get_post_type() == 'post') {
    return true;
  }
  return false;
}

onesignal_include_post

强制为特定文章类型发送通知：

<?php
add_filter('onesignal_include_post', 'include_pages', 10, 3);

function include_pages($new_status, $old_status, $post) {
  // 在页面发布时发送通知
  if ($post->post_type == "page" && $new_status == "publish") {
    return true;
  }
  return false;
}

onesignal_meta_box_send_notification_checkbox_state

控制通知复选框的默认状态：

<?php
add_filter('onesignal_meta_box_send_notification_checkbox_state', 'auto_check_checkbox', 10, 2);

function auto_check_checkbox($post, $settings) {
  // 总是为新闻类别的文章勾选此框
  if (has_category('news', $post)) {
    return true;
  }
  return false;
}

混合 WordPress/非 WordPress 站点

对于同时具有 WordPress 和非 WordPress 页面的站点：

在 OneSignal 仪表板中使用自定义代码设置
将此代码添加到非 WordPress 页面：

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
var OneSignal = window.OneSignal || [];
var initConfig = {
  appId: "YOUR_APP_ID_FROM_WORDPRESS_PLUGIN",
  notifyButton: {
    enable: true
  },
};
OneSignal.push(function () {
  OneSignal.SERVICE_WORKER_PARAM = {
    scope: '/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/'
  };
  OneSignal.SERVICE_WORKER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.SERVICE_WORKER_UPDATER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.init(initConfig);
});
</script>

故障排除

常见问题

“没有收件人”错误

**原因：**试图对同一文章过于快速地发送多个通知
**解决方案：**对于同一文章的通知之间至少等待一分钟

提示未出现

**原因：**缓存插件、浏览器设置或初始化问题
解决方案：
- 清理所有缓存插件
- 检查浏览器通知权限
- 验证 HTTPS 已启用
- 确认插件配置已保存

“无法加载 wp.data”警告

**带有 Gutenberg 的 WordPress 5+：**可能表示设置问题 - 联系支持
**WordPress 4.x：**可以安全忽略 - 此警告不会影响功能

自定义文章类型不工作

**原因：**缺少所需的元数据
**解决方案：**使用 onesignal_include_post 过滤器显式包含您的文章类型

通知未计划

**原因：**WordPress cron 或主题冲突
解决方案：
1. 使用 OneSignal 仪表板或 API 进行计划
2. 使用 onesignal_send_notification 过滤器实现自定义计划
3. 使用 Zapier 集成进行自动化

数据库条目

OneSignal 在您的 wp_postmeta 表中创建这些条目：

条目	描述
`onesignal_meta_box_present`	确认文章发布时 OneSignal 处于活跃状态
`onesignal_send_notification`	跟踪通知发送
`status`	通知的 HTTP 状态（200 = 成功）
`response_body`	带有通知 ID 和收件人计数的 API 响应
`recipients`	接收通知的用户数量

获取帮助

**插件问题：**查看 WordPress 网页推送故障排除
**通用支持：**联系 support@onesignal.com
**插件源码：**可在 GitHub 上获取

后续步骤

完成此设置后：

**监控性能：**定期检查您的 OneSignal 仪表板以了解订阅者增长和参与指标
**优化提示：**试验不同的提示时间和消息传递
**用户分段：**实施标记以发送更有针对性的通知
**彻底测试：**向不同设备和浏览器发送测试通知
**制定内容策略：**制定一个在不让用户感到负担的同时增加价值的通知策略

对于 A/B 测试、高级细分和详细分析等高级功能，请考虑升级到 OneSignal 付费计划。

Using the REST APIs

API reference

SDKs

​前置条件

​步骤 1：选择集成

​步骤 2：站点设置

​步骤 3：高级推送设置（可选）

​步骤 4：配置 WordPress 插件

​安装插件

​配置 API 密钥

​启用推送提示

​步骤 5：测试您的设置

​验证安装

​发送测试通知

​步骤 6：配置通知提示

​订阅铃铛

​滑动提示

​步骤 7：自动文章通知

​基本设置

​自动启用通知

​欢迎通知

​高级自定义

​自定义订阅提示

​Advanced Prompt Setup

步骤 1：禁用默认提示

步骤 2：启用手动初始化

步骤 3：添加自定义 JavaScript

​页面特定提示

服务器端 PHP 方法

客户端 JavaScript 方法

​多语言提示

​用户分段与定向

​标记用户

​定向细分市场

​通知中的特色图片

​启用特色图片支持

​配置图片设置

​第三方插件集成

​标准文章类型

​自定义文章类型

​移动应用集成

​方法 1：简单的网页浏览器打开

​方法 2：深度链接

​WordPress 插件钩子和过滤器

​代码放置

​onesignal_send_notification

​onesignal_initialize_sdk

​onesignal_include_post

​onesignal_meta_box_send_notification_checkbox_state

​混合 WordPress/非 WordPress 站点

​故障排除

​常见问题

​“没有收件人”错误

​提示未出现

​“无法加载 wp.data”警告

​自定义文章类型不工作

​通知未计划

​数据库条目

​获取帮助

​后续步骤

前置条件

步骤 1：选择集成

步骤 2：站点设置

步骤 3：高级推送设置（可选）

步骤 4：配置 WordPress 插件

安装插件

配置 API 密钥

启用推送提示

步骤 5：测试您的设置

验证安装

发送测试通知

步骤 6：配置通知提示

订阅铃铛

滑动提示

步骤 7：自动文章通知

基本设置

自动启用通知

欢迎通知

高级自定义

自定义订阅提示

Advanced Prompt Setup

页面特定提示

多语言提示

用户分段与定向

标记用户

定向细分市场

通知中的特色图片

启用特色图片支持

配置图片设置

第三方插件集成

标准文章类型

自定义文章类型

移动应用集成

方法 1：简单的网页浏览器打开

方法 2：深度链接

WordPress 插件钩子和过滤器

代码放置

onesignal_send_notification

onesignal_initialize_sdk

onesignal_include_post

onesignal_meta_box_send_notification_checkbox_state

混合 WordPress/非 WordPress 站点

故障排除

常见问题

“没有收件人”错误

提示未出现

“无法加载 wp.data”警告

自定义文章类型不工作

通知未计划

数据库条目

获取帮助

后续步骤