WooCommerce 集成

Pushwoosh for WooCommerce 插件将您的 WordPress 商店连接到 Pushwoosh。客户会成为电子邮件和 SMS 联系人，订单和废弃购物车会成为可用于启动 Customer Journey 的事件，您的店面还会获得带订阅铃铛的 Web 推送。

需要开发人员协助

您需要开发团队或 WordPress 网站运维人员的帮助来安装插件并设置几个服务器端选项。请与他们分享本指南。

集成概述

WooCommerce 是一款适用于 WordPress 的开源电子商务插件。Pushwoosh for WooCommerce 插件通过 Pushwoosh API 将您的商店数据直接发送到 Pushwoosh。插件在后台发送数据，因此不会拖慢结账速度。

集成类型

目标：此集成将数据从您的 WooCommerce 商店推送到 Pushwoosh。

先决条件

• WordPress 6.4 或更高版本、WooCommerce 8.2 或更高版本，以及 PHP 8.1 或更高版本
• WordPress 网站的管理员访问权限
• 一个 Pushwoosh 账户，其中包含用于您商店的应用
• 如果要使用 Web 推送，需要 HTTPS 网站地址。浏览器只会在 HTTPS 网站上注册 Web 推送。

该插件支持高性能订单存储 (HPOS)，并同时支持经典版和区块版的购物车 (Cart) 与结账 (Checkout) 页面。

插件同步的内容

下表显示了每个 WooCommerce 实体在 Pushwoosh 中对应的内容：

WooCommerce	Pushwoosh
客户或访客买家	带有电子邮件联系人的用户；如果电话号码是有效的手机号码，还会带有 SMS 联系人
客户姓名、同意状态和已映射字段	标签 (Tags)
订单创建、更新或取消	PW_OrderCreated、PW_OrderUpdated、PW_OrderCanceled 事件
废弃购物车	PW_AbandonedCart 和 PW_AbandonedCartUpdate 事件，附带可恢复购物车的链接
允许通知的店面访客	与客户电子邮件关联的 Web 推送订阅者

Pushwoosh 中的 User ID 是客户电子邮件地址的小写形式：注册客户使用账户电子邮件，访客使用账单电子邮件。同一客户的联系人、事件和 Web 推送订阅者都会归到同一个用户下。

用例

• 当购物者在购物车中留下商品时，发送电子邮件或推送，并附带可恢复该购物车的按钮。
• 在下单后感谢买家，在订单发货时跟进，或在取消订单后挽回客户。
• 按城市、国家/地区或您映射到标签的任何客户字段对客户进行细分。
• 向通过铃铛订阅的店面访客发送 Web 推送促销。

准备您的 Pushwoosh 应用

请在启用插件之前完成以下步骤。如果插件发送了一个尚不存在的事件，Pushwoosh 会自动创建该事件，并根据收到的第一批值推测属性类型。推测的类型可能是错误的（例如，价格被保存为整数），而在您修正类型之前发送的数据会丢失。

创建 API 令牌

该插件使用两个 Device API token。在 Settings → API Access 中创建这两个令牌，并授予它们访问您应用的权限：

1. 为服务器创建一个 Device API token。插件使用它来注册联系人和发送事件。它永远不会离开您的服务器。
2. 为店面创建第二个 Device API token。插件会将它输出到每个店面页面中以启动 Web 推送，因此它是公开的。使用单独的令牌，您可以在不改动服务器令牌的情况下替换它。

Server API token 是可选的。有了它，插件设置中会显示您应用中的标签列表，这在将客户字段映射到标签时很有帮助。

创建事件

在 Audience → Events → Create Event → Custom Event 中创建五个自定义事件：PW_OrderCreated、PW_OrderUpdated、PW_OrderCanceled、PW_AbandonedCart 和 PW_AbandonedCartUpdate。了解如何创建自定义事件。

为每个事件添加它所接收的属性，并使用以下类型：

属性	类型	事件
orderId	string	全部
source	integer	全部
orderNumber、status、wcStatus	string	订单事件
email、customerId、shippingMethod、currency	string	全部
orderUrl	string	购物车事件
totalPrice、shippingAmount、discountAmount	decimal (price)	全部
taxAmount	decimal (price)	订单事件
createdDate	date	全部
updatedDate	date	订单事件
abandonedDate	date	购物车事件
items	list	全部
historical	boolean	订单事件

如果您的订单事件中 orderId 已设置为 integer，请将其改为 string。如果使用 integer，Pushwoosh 不会将该订单的商品计为电子邮件 Products 区块中畅销品推荐的销量。

创建标签

在标签页面上创建以下标签：

标签	类型
firstName	string
lastName	string
acceptsMarketing	integer

此外，请为您计划映射的每个客户字段创建一个标签，如将客户字段映射到标签中所述。默认映射使用 City 和 Country 标签。

配置 Web 推送

要使用 Web 推送，请为您的应用设置 Web 平台。请参阅 Web 推送配置。

安装插件

1. 在 WordPress 管理面板中，转到 Plugins → Add New Plugin。
2. 搜索 Pushwoosh for WooCommerce。
3. 点击 Install Now。
4. 点击 Activate。WooCommerce 必须已处于激活状态。

您也可以从 wordpress.org 下载插件 zip 包，然后在 Plugins → Add New Plugin → Upload Plugin 中上传。

低流量商店

插件通过 WooCommerce 的 Action Scheduler 在后台发送数据，而 Action Scheduler 运行在 WP-Cron 上。WP-Cron 只有在有人访问网站时才会触发，因此在访客较少的商店中，事件可能会延迟到达。请让您的开发人员改为通过系统 cron 作业运行 WP-Cron：在 wp-config.php 中将 DISABLE_WP_CRON 设置为 true，并每分钟运行一次 wp cron event run --due-now。

将插件连接到 Pushwoosh

转到 WooCommerce → Settings → Pushwoosh，并填写 Connection 部分：

1. 将 API URL 保留为 https://api.pushwoosh.com，除非 Pushwoosh 支持团队为您提供了其他地址。
2. 在 Application code 中，输入您的应用代码。
3. 在 Device API token 中，粘贴您创建的服务器令牌。
4. 在 Web SDK token 中，粘贴店面令牌。
5. 可选：在 Server API token (optional) 中，粘贴 Server API token。
6. 点击 Save changes。
7. 点击 Check connection。

Check connection 会验证：

• API URL
• 应用代码和令牌
• 发送队列
• Web 推送 service worker（如果已开启 Web 推送）

它不会发送测试事件，因为测试事件会创建属性为空的事件。如果检查结果显示无法验证令牌，说明您的应用接受任何 Device API token。请联系 Pushwoosh 支持团队为该应用开启 Device API token 校验。

已保存的令牌会以掩码形式显示。要保留已保存的令牌，请在保存设置时将其字段留空。

启用模块

在 Modules 部分，开启您要发送的数据，然后点击 Save changes：

• Sync customers： 在客户注册时以及每次保存其个人资料时，将客户注册为 Pushwoosh 中的联系人。
• Send order events： 发送订单事件。只有在您开启此选项后创建的订单才会收到 PW_OrderCreated。要发送过去的订单，请参阅导入现有客户和订单。
• Send abandoned cart events： 发送购物车事件。将 Cart is abandoned after, minutes 设置为购物车在发送 PW_AbandonedCart 之前必须保持未改动的时长。默认值为 60，最小值为 15。
• Enable web push on the storefront： 在每个店面页面上加载 Web 推送。请参阅设置 Web 推送。
• Require marketing consent： 对于未同意接收营销信息的客户，不发送任何数据。请参阅收集营销同意。
• Delete all data when the plugin is deleted： 删除插件时，同时移除其设置、其在用户和订单记录中的数据以及排队的作业。无论此选项是否开启，已跟踪购物车的表都会被移除。已在 Pushwoosh 中的数据会保留。

将客户字段映射到标签

在 Customer tags 部分，使用 Field → tag mapping 将更多客户数据作为标签发送。每行写一个 source = Tag 对：

billing_city = City
billing_country = Country
shipping_postcode = Postcode
meta:loyalty_level = Loyalty level

• Source 是客户字段，例如 billing_city 或 shipping_postcode，或者是 meta: 后跟用户或订单的 meta 键。
• Tag 是您的 Pushwoosh 应用中已存在的标签名称。

firstName、lastName 和 acceptsMarketing 始终会被发送，因此您无需映射它们。保存 Server API token 后，该部分会列出您应用中已存在的标签，并显示被忽略的映射行。

收集营销同意

插件会在注册表单以及经典版和区块版结账页面中添加复选框 I agree to receive news and offers by email and SMS。客户的选择会存储在客户和订单上，并作为 acceptsMarketing 标签（1 或 0）发送。已经同意的客户不会再次看到该复选框，之后订单中未勾选的复选框也不会撤回之前的同意。

Require marketing consent 带来的变化：

• 关闭（默认）： 每个客户都会注册为联系人，acceptsMarketing 会告诉您哪些客户已同意。可在细分中使用它来筛选受众。
• 开启： 未同意的客户不会获得电子邮件或 SMS 联系人，其订单不会发送事件，其购物车也不会发送购物车事件。

开启该选项时，现有联系人不会立即被移除。之前在未同意的情况下同步的注册客户，会在下次保存其个人资料时或您再次运行客户导入时从 Pushwoosh 中删除。访客联系人不会被删除。

区块版结账页面在 WooCommerce 8.9 及更高版本中显示该复选框。在更早的版本中，如果开启了 Require marketing consent，来自该结账页面的购物车不会发送事件。

插件发送的事件和标签

本节列出了插件发送的所有事件和标签，方便您基于它们构建细分和 Customer Journey。

联系人和标签

插件将每个客户注册为电子邮件联系人；当账单电话是有效的手机号码时，还会注册为 SMS 联系人。联系人的语言是客户注册或结账时使用的商店语言。每个联系人都会获得以下标签：

标签	值
firstName	账单名字；如果账单为空，则为账户名字
lastName	账单姓氏；如果账单为空，则为账户姓氏
acceptsMarketing	如果客户同意接收营销信息则为 1，否则为 0
已映射的标签	您字段映射中字段的值

插件会在以下时机同步客户：

• 注册客户： 在注册时以及每次保存其个人资料时。
• 访客买家： 开启 Sync customers 后，根据其订单同步。
• 废弃购物车的访客： 在购物车事件发送前，从而使该事件有对应的用户。
• 更改账户电子邮件的客户： 插件会删除 Pushwoosh 中的旧用户并注册新用户。

Pushwoosh 会拒绝某些联系人，插件不会重试它们：使用无效或一次性域名的电子邮件，以及非手机号码的电话号码。这些情况会按照检查集成是否正常工作中的说明记录到日志中。

订单事件

每当订单状态发生变化时，插件都会发送一个事件：

事件	发送时机
PW_OrderCreated	在您开启 Send order events 之后创建的订单首次同步时发送，无论其当时处于何种状态
PW_OrderUpdated	除取消之外的每次后续状态变化。对于在您开启 Send order events 之前创建的订单，这也是其第一个事件。
PW_OrderCanceled	订单变为 Cancelled 状态

草稿订单和失败订单不会发送事件。

Pushwoosh 还会将 PW_OrderCreated 和 PW_OrderUpdated 中的商品计为电子邮件 Products 区块中畅销品推荐的销量。

status 属性使用与 Magento 集成相同的值，因此为 Magento 构建的 Customer Journey 无需更改即可使用。原始的 WooCommerce 状态位于 wcStatus 中：

WooCommerce 状态	status
Pending payment、On hold	pending
Processing	processing
Completed	complete
Refunded	closed
Cancelled	canceled
自定义状态	原样使用状态 slug

每个订单事件都包含以下属性：

属性	值
orderId	订单 ID
orderNumber	向客户显示的订单号
source	始终为 1
email	账单电子邮件
customerId	User ID：账户电子邮件，访客则为账单电子邮件
items	订购的产品，见下文
createdDate、updatedDate	订单的创建日期和最后更改日期，采用商店时区
shippingMethod	第一个配送方式的名称
totalPrice	订单总额
shippingAmount、taxAmount、discountAmount	运费、税费和折扣总额
currency	订单货币代码
status、wcStatus	订单状态，见上表
historical	导入时发送的过去订单为 true，否则为 false

items 中的每个条目都包含 productId、sku、name、description（简短描述）、price（不含税的单价）、quantity、imageUrl、productUrl 和 category（以逗号分隔的类别名称）。

PW_OrderCreated 属性示例：

{
  "orderId": "1042",
  "orderNumber": "1042",
  "source": 1,
  "email": "jane@example.com",
  "customerId": "jane@example.com",
  "items": [
    {
      "productId": "17",
      "sku": "TSHIRT-M",
      "name": "T-shirt",
      "description": "Cotton T-shirt",
      "price": 20.0,
      "quantity": 2,
      "imageUrl": "https://shop.example.com/wp-content/uploads/tshirt.jpg",
      "productUrl": "https://shop.example.com/product/t-shirt/",
      "category": "Clothing, T-shirts"
    }
  ],
  "createdDate": "2026-09-30T12:00:00+02:00",
  "updatedDate": "2026-09-30T12:00:00+02:00",
  "shippingMethod": "Flat rate",
  "totalPrice": 47.6,
  "shippingAmount": 5.0,
  "taxAmount": 7.6,
  "discountAmount": 5.0,
  "currency": "EUR",
  "status": "pending",
  "wcStatus": "on-hold",
  "historical": false
}

废弃购物车事件

当购物车包含电子邮件、未改动的时间超过 Cart is abandoned after, minutes，且没有从中下单时，该购物车即被视为废弃：

事件	发送时机
PW_AbandonedCart	购物车首次被废弃时
PW_AbandonedCartUpdate	同一购物车在 PW_AbandonedCart 之后发生变化并再次被废弃时

插件每 15 分钟检查一次购物车，因此事件通常会在达到阈值后的 15 分钟内到达。

如果购物者在此之前从同一会话或使用同一账单电子邮件下单，购物车将被关闭，不会发送事件。已关闭的购物车如果被购物者重新填充，会重新从 PW_AbandonedCart 开始。

插件需要购物者的电子邮件才能发送购物车事件：

• 已登录的购物者： 账户电子邮件。
• 访客： 结账时在账单电子邮件字段中输入的电子邮件，即使订单从未提交。

购物车事件属性包括 orderId（购物车 ID）、source、email、customerId、items、createdDate、abandonedDate（购物车最后更改的时间）、shippingMethod、totalPrice、shippingAmount、discountAmount、currency 和 orderUrl。在购物车事件中，商品价格含税。

购物车恢复链接

orderUrl 是一个可恢复购物者购物车的链接。请将其用作提醒中的按钮链接：

• 打开该链接会将已保存的商品放入购物车，并将购物者带到结账页面。它适用于任何浏览器，包括购物者从未访问过您商店的浏览器。
• 该链接不会让任何人登录。
• 该链接有效期为 14 天。从该购物车下单后，或购物车被删除后，该链接会改为打开访客的普通购物车页面。

删除插件后，恢复链接将失效，即使您重新安装插件也是如此，因为用于签名这些链接的密钥会随插件一起被删除。

构建废弃购物车 Customer Journey

此示例会发送一封包含购物车商品和恢复购物车按钮的电子邮件。它需要同时开启 Send abandoned cart events 和 Send order events，以便 Customer Journey 能够判断购物者何时完成了购买。

创建电子邮件

在电子邮件内容编辑器中创建电子邮件，然后通过以下两种方式之一显示购物车商品：

• Products 区块： 显示 Pushwoosh 在发送时存储的购物车。如果购物者在 PW_AbandonedCart 之后更改了购物车，电子邮件会显示最新的商品。
• Liquid： 以您自行编写的任意布局，显示启动 Customer Journey 的 PW_AbandonedCart 事件中的商品。

使用 Products 区块显示商品

1. 在电子邮件中添加 Products 区块。
2. 将 Source 设置为 Cart。
3. 设置 Max products shown。

Cart 来源需要您的套餐中包含 Content Templates，并需要在 Settings → API Access 中有一个 API 访问令牌。没有令牌，电子邮件将无法保存。

使用 Liquid 显示商品

使用 Liquid 将购物车内容添加到电子邮件正文中。占位符的值来自启动 Customer Journey 的 PW_AbandonedCart 事件：

<p>Your cart total is {{ totalPrice }} {{ currency }}.</p>
<table>
  {% for item in items %}
  <tr>
    <td><img src="{{ item.imageUrl }}" width="64" alt=""></td>
    <td><a href="{{ item.productUrl }}">{{ item.name }}</a></td>
    <td>× {{ item.quantity }}</td>
    <td>{{ item.price }} {{ currency }}</td>
  </tr>
  {% endfor %}
</table>

添加恢复按钮

Products 区块不会添加恢复购物车的链接，因此无论使用哪种方式显示商品，都请添加此按钮：

1. 在电子邮件中添加一个按钮。
2. 将按钮链接设置为 {{ orderUrl }}。
3. 保存电子邮件。

构建 Customer Journey

1. 添加使用 PW_AbandonedCart 事件的基于触发器的入口。
2. 添加一个 Wait for Trigger 步骤。
3. 设置其等待时间，例如 1 小时。
4. 在 Wait for Trigger 中，将分支命名为 Order placed。
5. 将 PW_OrderCreated 事件添加到 Order placed 分支。
6. 使用退出元素结束 Order placed 分支，或使其没有传出连接。购物者已经完成了购买。
7. 将 Not triggered 分支路由到电子邮件步骤。
8. 在电子邮件步骤中，选择您创建的电子邮件。
9. 在电子邮件步骤中，开启 Overwrite Liquid placeholders 并选择 PW_AbandonedCart 事件。
10. 在电子邮件步骤之后，使用 Exit 元素结束该分支，或使其没有传出连接。
11. 启动 Customer Journey。

插件在发送 PW_AbandonedCart 之前，已经等待了 Cart is abandoned after, minutes 设定的时间。Wait for Trigger 中的等待时间会叠加在该时间之上，因此请将其设置得短一些。

在 Wait for Trigger 本身上设置等待时间，不要在它之前添加单独的 Time Delay 步骤。

Wait for Trigger 只会捕获购物者到达该步骤之后发送的 PW_OrderCreated。在 Time Delay 期间下单的购物者仍然会收到提醒，而其中的 Products 区块不会显示任何商品，因为订单会清除该区块用于读取购物车的 PW_AbandonedCartID 标签。

如果要改用推送来提醒购物者，请使用推送步骤，并开启 Personalize message with event attributes 以插入 orderUrl 或 totalPrice。请参阅Customer Journey 中的 Dynamic Content 和 Liquid Templates。

设置 Web 推送

开启 Web 推送后，每个店面页面都会加载 Pushwoosh Web SDK，访客可以订阅来自您商店的通知。

选择请求访客订阅的方式：

• Subscribe bell on the page (works in every browser)： 在页面角落显示一个铃铛。访客点击后，浏览器会请求权限。这是默认选项。
• Ask on page load (Chrome and Edge only)： 页面一打开，浏览器就会请求权限。Safari 以及大多数情况下的 Firefox 只会在点击后显示权限请求，因此这些浏览器中的访客根本不会收到请求。

要开启 Web 推送：

1. 确保您的应用中已配置 Web 平台，如配置 Web 推送中所述。
2. 在 WooCommerce → Settings → Pushwoosh 中，填写 Web SDK token。
3. 开启 Enable web push on the storefront。
4. 在 Web push subscription 中，选择请求访客订阅的方式。
5. 点击 Save changes。
6. 点击 Check connection，确保 service worker 能够加载。

您可以在应用的 Web 推送配置中更改铃铛文本、订阅提示、默认通知标题和图像以及 Safari 设置。这些设置会覆盖插件的默认值。

订阅者如何与客户关联

新订阅者最初是匿名的。插件会在以下时机将订阅者关联到 Pushwoosh 中该客户的用户：

• 客户登录之后。
• 在订单确认页面上，适用于每位买家，包括访客。

当客户退出登录或撤回同意时，登录时建立的关联会被移除。开启 Require marketing consent 后，只有当客户或订单已获得同意时，订阅者才会被关联。

Service worker

插件从您网站的 /pushwoosh-sw/ 提供 Web 推送 service worker，并将其从 WP Rocket、LiteSpeed Cache 和 W3 Total Cache 的页面缓存中排除。如果 Check connection 报告 service worker 状态错误，请让您的开发人员检查该 URL 是否被服务器阻止或缓存。

该 service worker 覆盖整个网站，因此会替换在网站根目录注册的任何其他 service worker，例如来自 PWA 插件或其他推送服务提供商的 service worker。您的开发人员可以使用 pushwoosh_wc_service_worker_imports 过滤器添加该其他 service worker 的脚本。

导入现有客户和订单

在 WooCommerce → Settings → Pushwoosh 的 Historical sync 部分，发送安装插件之前已存在的客户和订单：

• Sync existing customers： 注册所有具有 Customer 角色的客户，然后注册过去订单中的访客买家。
• Send past orders： 为每个从未发送过事件的过去订单发送一个 historical 设置为 true 的 PW_OrderCreated 事件。已取消的订单会被跳过。

该部分会显示每次运行的进度。两种运行都只会将调用加入队列，由 Action Scheduler 在后台发送。

在订单 Customer Journey 中过滤掉过去的订单

每个过去的订单都会发送 PW_OrderCreated。在以此事件启动的 Customer Journey 中，请为入口添加事件属性条件：historical 等于 false。否则，客户会因旧订单收到“感谢您的订购”消息。

对于大型商店，请让您的开发人员使用 WP-CLI 运行导入。添加 --since=YYYY-MM-DD 以仅导入从该日期起的记录：

wp pushwoosh sync customers --since=2025-01-01
wp pushwoosh sync orders --historical --since=2026-01-01

导出和擦除个人数据

该插件可与 WordPress 的个人数据工具配合使用，位于 Tools → Export Personal Data 和 Tools → Erase Personal Data：

• Export 包含插件保存的有关客户的数据：已同步的电子邮件、同意选择、语言以及客户被跟踪的购物车。
• Erase 会删除这些数据和客户被跟踪的购物车，取消该电子邮件待处理的 Pushwoosh 调用，并删除 Pushwoosh 中的用户及其联系人。除非客户在之后的结账中勾选同意复选框，否则不会再次同步该客户。

擦除不会移除订单。WooCommerce 保留的订单在状态变化时，仍会使用其账单电子邮件发送订单事件。订单是否匿名化由 WooCommerce 自身的隐私设置决定。

请将您发送给 Pushwoosh 的数据添加到商店的隐私政策中。

检查集成是否正常工作

1. 使用一个您能查找到的电子邮件下一个测试订单，并勾选同意复选框。
2. 打开 User Explorer 并搜索该电子邮件。
3. 检查该用户是否有带 firstName、lastName 和 acceptsMarketing 标签的电子邮件联系人。
4. 检查该用户的事件中是否包含 PW_OrderCreated。

如果数据没有到达，请打开 WooCommerce → Status → Logs 并选择 pushwoosh 来源。日志会显示每个失败的调用及其原因。令牌永远不会被记录，电子邮件会以掩码形式显示。

插件处理错误的方式：

• 网络错误和临时服务器错误： 在 1、5、15、60 和 240 分钟后重试调用，之后记录为错误。
• 被拒绝的数据，例如使用一次性电子邮件域名的联系人：记录为错误，不会重试。
• 被拒绝的令牌： 发送暂停，WordPress 管理后台会显示一条带有 Resume sending 按钮的通知。已排队的调用会被保留。请在设置中修正令牌，然后点击 Resume sending。