> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress 旧版设置

> 使用 2.x.x 版本插件在 WordPress 站点上设置和自定义 OneSignal 网页推送通知的完整指南，包括高级自定义、提示和故障排除

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

<Warning>
  本指南专针 OneSignal WordPress 插件版本 2.x.x。对于版本 3+，请参阅我们更新的 [WordPress 文档](./wordpress)。
</Warning>

## 前置条件

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

***

## 步骤 1：选择集成

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

<Frame caption="平台选择界面显示网页选项">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7d3f2f0-Screen_Shot_2021-07-05_at_11.40.52_AM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=571b00b4e1940952a9fd8e71a21b712b" width="2140" height="1068" data-path="images/docs/7d3f2f0-Screen_Shot_2021-07-05_at_11.40.52_AM.png" />
</Frame>

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

<Frame caption="网页推送集成选项，突出显示 WordPress 插件">
  <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/ccf9939-Screen_Shot_2021-07-05_at_10.32.06_AM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=4f71785d2f435a01e88d22e4129416f7" width="2002" height="1188" data-path="images/docs/ccf9939-Screen_Shot_2021-07-05_at_10.32.06_AM.png" />
</Frame>

## 步骤 2：站点设置

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

<Frame caption="站点设置配置表单及必填字段">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/662221c-site-setup.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=69d48a03d1017b54075ad710fcd6297f" width="1379" height="1019" data-path="images/docs/662221c-site-setup.jpg" />
</Frame>

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

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

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

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

<Frame caption="高级推送设置显示 Safari 证书上传选项">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/f21e43f-configure-3.jpg?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=0a2f7a2e408114044ef5d28316d13515" width="1204" height="660" data-path="images/docs/f21e43f-configure-3.jpg" />
</Frame>

**何时使用自定义证书：**

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

## 步骤 4：配置 WordPress 插件

### 安装插件

从您的 WordPress 管理员界面或通过在插件目录中搜索“OneSignal”来添加 [OneSignal WordPress 插件](https://wordpress.org/plugins/onesignal-free-web-push-notifications/)。

### 配置 API 密钥

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

<Frame caption="OneSignal 仪表板显示 App ID 和 API 密钥位置">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6b4aa29-Screen_Shot_2021-07-05_at_11.01.07_AM.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=89fe32e989732751692914160cffa080" width="1748" height="862" data-path="images/docs/6b4aa29-Screen_Shot_2021-07-05_at_11.01.07_AM.png" />
</Frame>

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

<Frame caption="WordPress 插件配置显示 API 密钥输入字段">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/9d3d86a-Screen_Shot_2021-07-05_at_11.05.05_AM.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=f225d715a688a6efc6b50f26cafca73a" width="2008" height="1270" data-path="images/docs/9d3d86a-Screen_Shot_2021-07-05_at_11.05.05_AM.png" />
</Frame>

### 启用推送提示

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

<Frame caption="提示设置显示滑动提示和订阅铃铛选项">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/edc7cb2-Screen_Shot_2021-07-05_at_11.16.22_AM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=45914ab2ed670a56015a4b62f33e4d3b" width="2382" height="1082" data-path="images/docs/edc7cb2-Screen_Shot_2021-07-05_at_11.16.22_AM.png" />
</Frame>

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

<Frame caption="配置页面底部的保存按钮位置">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/289d5d6-Screen_Shot_2021-07-05_at_11.11.18_AM.png?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=5929ec4f86fa8e60d174d6b688b1dd1d" width="2008" height="660" data-path="images/docs/289d5d6-Screen_Shot_2021-07-05_at_11.11.18_AM.png" />
</Frame>

## 步骤 5：测试您的设置

### 验证安装

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

### 发送测试通知

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

<Info>
  \*\*故障排除：\*\*如果提示未出现，请检查[推送通知是否在您的设备设置中启用](./notifications-not-shown-web-push#notifications-are-blocked-in-settings)，并尝试清理您的浏览器缓存。
</Info>

## 步骤 6：配置通知提示

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

### 订阅铃铛

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

### 滑动提示

一个根据您的时间设置出现的模态对话框，用于请求权限。

\*\*后续步骤：\*\*用户通常希望自定义提示时间和外观。请参见下面的[高级自定义](#advanced-customizations)部分。

## 步骤 7：自动文章通知

### 基本设置

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

<Frame caption="文章编辑器显示 OneSignal 通知复选框">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/69f208a-Screen_Shot_2021-08-09_at_6.10.41_PM.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=3be4ccf2e8e3631de57b44f4e4039d39" width="1990" height="1248" data-path="images/docs/69f208a-Screen_Shot_2021-08-09_at_6.10.41_PM.png" />
</Frame>

### 自动启用通知

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

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

<Frame caption="自动通知设置显示自动发送选项">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4af55ad-Screen_Shot_2021-08-09_at_6.18.37_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=15a266483293e49d5e133b3c95960bc6" width="1966" height="368" data-path="images/docs/4af55ad-Screen_Shot_2021-08-09_at_6.18.37_PM.png" />
</Frame>

### 欢迎通知

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

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

***

## 高级自定义

OneSignal WordPress 插件使用您配置的选项加载我们的网页推送 SDK。您可以使用任何 [网页推送 SDK JavaScript APIs](./web-sdk-reference) 来进一步自定义体验。

<Info>
  \*\*开发者注释：\*\*此部分需要 JavaScript 和 PHP 知识。如果您需要帮助将代码添加到您的站点，请考虑使用 [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/) 或 [Custom CSS & JS](https://wordpress.org/plugins/custom-css-js/) 等插件。
</Info>

### 自定义订阅提示

#### Advanced Prompt Setup

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

##### 步骤 1：禁用默认提示

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

<Frame caption="提示设置显示已禁用的滑动和原生提示">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/ff12526-Screen_Shot_2021-09-01_at_11.03.54_AM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=4a4aea38a75939cd1845d9a4f9ec6b0c" width="2676" height="1054" data-path="images/docs/ff12526-Screen_Shot_2021-09-01_at_11.03.54_AM.png" />
</Frame>

##### 步骤 2：启用手动初始化

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

<Frame caption="高级设置显示手动初始化开关">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7ba0ca1-Screen_Shot_2021-08-09_at_8.32.28_PM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=773629edeb5a2099250b9d171dea6c13" width="1798" height="606" data-path="images/docs/7ba0ca1-Screen_Shot_2021-08-09_at_8.32.28_PM.png" />
</Frame>

##### 步骤 3：添加自定义 JavaScript

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

```javascript theme={null}
// 基本延迟提示
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);
```

```javascript theme={null}
// 基于分类的提示
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` 过滤器](#onesignal_initialize_sdk-filter) 来根据页面属性控制初始化。

##### 客户端 JavaScript 方法

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

#### 多语言提示

对于单语言站点，只需在提示配置中翻译文本即可。

对于多语言站点，使用上面的手动初始化方法并检测页面语言以显示适当的文本。

### 用户分段与定向

#### 标记用户

使用[数据标签](./add-user-data-tags)对用户进行分类，以发送有针对性的通知：

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

#### 定向细分市场

在您的 OneSignal 仪表板中使用 **用户标签** 过滤器创建[细分市场](./segmentation)，然后使用 `onesignal_send_notification` 过滤器对其进行定向：

```php theme={null}
<?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` 中是否有：

```php theme={null}
add_theme_support('post-thumbnails');
```

#### 配置图片设置

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

<Frame caption="特色图片设置显示图标和大图片选项">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/fafaeea-Screen_Shot_2021-08-09_at_8.24.33_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=58f3d8299d0ca28087661a2dacf63a2d" width="1752" height="266" data-path="images/docs/fafaeea-Screen_Shot_2021-08-09_at_8.24.33_PM.png" />
</Frame>

### 第三方插件集成

#### 标准文章类型

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

<Frame caption="第三方插件集成设置">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/gxAslQH.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=95163a1e8e50ed70b7197dda49d82ac6" width="1172" height="836" data-path="images/docs/gxAslQH.png" />
</Frame>

#### 自定义文章类型

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

<Frame caption="自定义文章类型配置字段">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/TQ2LsBu.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=1cea147dc5fcc005e8580c226997859f" width="1172" height="836" data-path="images/docs/TQ2LsBu.png" />
</Frame>

**查找自定义文章类型：**
创建自定义文章类型时查看您浏览器的 URL：
`https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type`

`post_type` 参数显示要添加的名称。

### 移动应用集成

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

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

<Frame caption="移动平台集成开关">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1d64470-c33ad19-cr3uBcL.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=40948b57a6a8755ad0956d08120ef01e" width="580" height="64" data-path="images/docs/1d64470-c33ad19-cr3uBcL.png" />
</Frame>

#### 方法 2：深度链接

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

```php theme={null}
<?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 插件钩子和过滤器

#### 代码放置

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

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

#### onesignal\_send\_notification

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

```php theme={null}
<?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 theme={null}
<?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 theme={null}
<?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 theme={null}
<?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 页面的站点：

1. 在 OneSignal 仪表板中使用[自定义代码设置](./web-push-custom-code-setup)
2. 将此代码添加到非 WordPress 页面：

```html theme={null}
<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 集成](./zapier) 进行自动化

## 数据库条目

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

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

## 获取帮助

* \*\*插件问题：\*\*查看 [WordPress 网页推送故障排除](./troubleshooting-wordpress-web-push)
* \*\*通用支持：\*\*联系 `support@onesignal.com`
* \*\*插件源码：\*\*可在 [GitHub](https://github.com/OneSignal/OneSignal-WordPress-Plugin) 上获取

***

## 后续步骤

完成此设置后：

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

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