---
title: "WooCommerce 集成指南 | Tajo"
description: "用 Tajo for WooCommerce 插件把你的 WooCommerce 店铺连接到 Tajo：互动事件、持久化投递，以及最小化的客户数据。正在开发中，尚未进行端到端验证。"
url: https://tajo.io/zh-cn/docs/ecommerce-platforms/woocommerce/
markdown: https://tajo.io/zh-cn/docs/ecommerce-platforms/woocommerce.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# WooCommerce 集成指南

[Set Noa](https://tajo.io/zh-cn/set-noa/)

本指南介绍如何把 WooCommerce 店铺连接到 Tajo。这套集成由两个相互配合的部分组成：

- **Tajo for WooCommerce 插件**：在 WordPress 内部实时捕获发生的互动事件（订单、购物车、退款、评价、表单提交），并通过一个持久化、带签名的发件箱把它们投递给 Tajo。2026 年 10 月 14 日，该插件在本地站点上完成了测试；投递到 Tajo 的环节尚未验证。
- **WooCommerce REST 连接**：Tajo 读取你店铺的客户、订单、商品、优惠券、退款和评价，用于历史数据导入和持续同步。仅使用 REST 的配置方式见 [WooCommerce 连接器参考](https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce/)。

营销自动化本身（通过 Brevo 及其他服务商发送邮件、短信和 WhatsApp 消息）在 Tajo 中配置，而不在插件里。插件的职责是把可信的事件送出 WordPress。

## 前置条件

- **WordPress 6.3+**，且拥有管理员权限
- **PHP 7.4+**
- **WooCommerce 7.0+**（插件在没有 WooCommerce 的 WordPress 站点上同样可用，此时电商适配器只是保持未激活状态）
- **Tajo 账号**，且已创建 WordPress 连接
- Tajo 端点启用 HTTPS（托管版 Tajo 始终满足）

## 第 1 步：安装 Tajo for WooCommerce 插件

### 手动安装

```bash
# Download the plugin
cd wp-content/plugins
wget https://tajo.io/downloads/woocommerce/tajo-woocommerce-latest.zip

# Verify and unzip
unzip tajo-woocommerce-latest.zip
```

然后在 WordPress 管理后台激活：

1. 进入 **Plugins → Installed Plugins**
2. 找到 “Tajo for WooCommerce”
3. 点击 **Activate**

你也可以通过 **Plugins → Add New → Upload Plugin** 直接上传 zip 包。每个版本都会在 [tajo.io/downloads/woocommerce/](https://tajo.io/downloads/woocommerce/tajo-woocommerce-1.0.0.zip.sha256) 一并发布 SHA-256 校验和。该插件尚未收录进 WordPress.org 插件目录；目前受支持的安装方式是手动安装。

## 第 2 步：配置连接

进入 **WooCommerce → Tajo**（在没有 WooCommerce 的站点上是 **Settings → Tajo**），填入 Tajo WordPress 连接中的三个值：

| 字段 | 值 |
| --- | --- |
| **Tajo 端点** | Tajo 中显示的 HTTPS webhook URL，例如 `https://alto.tajo.io/api/connectors/wordpress/webhooks/engagement` |
| **Binding ID** | 该连接在 Tajo 中的 binding ID |
| **签名密钥** | 共享密钥（32–256 个字符）。插件在激活时会生成一个足够强的本地密钥；把它粘贴到 Tajo，或者把 Tajo 的密钥粘贴到这里 |

无需在 `wp-config.php` 中添加任何 API key 常量。在这三个值保存之前，事件会安全地排队留在本地发件箱中。

然后端到端验证整条链路：

1. 点击 **Queue test event**，再点击 **Process now**。
2. 投递发件箱表中应显示该事件已投递。
3. 在 Tajo 中确认 `connection.test` 事件已到达 WordPress 连接。

## 插件会发送什么

每个事件都是一个紧凑、隐私最小化的信封，使用 HMAC-SHA256 签名。离开 WordPress 的只有互动身份字段（邮箱、手机号、本地 ID）以及范围受限的事件元数据，绝不包含姓名、通信地址、IP 地址、User Agent、评论正文、任意表单字段、订单备注或支付信息。

### WooCommerce 事件

| 钩子 | 事件 |
| --- | --- |
| `woocommerce_created_customer` / `woocommerce_update_customer` | `customer.created` / `customer.updated` |
| `woocommerce_new_product` / `woocommerce_update_product` | `product.created` / `product.updated` |
| `woocommerce_add_to_cart`、移除商品、使用或取消优惠券 | `cart.updated`（附购物车摘要，用于弃购流程） |
| `woocommerce_cart_emptied` | `cart.emptied` |
| `woocommerce_new_order` / `woocommerce_update_order` | `order.placed` / `order.updated` |
| `woocommerce_order_status_changed` | `order.status_changed`（完成时附带 `order.fulfilled`） |
| `woocommerce_payment_complete` | `order.paid` |
| `woocommerce_order_refunded` | `refund.created` |
| WooCommerce Subscriptions 状态更新 | `subscription.status_changed` |

订单事件携带订单号、状态、币种、总额、订单行，以及可直接使用的评价和再次下单 URL，足以支撑售后与赢回自动化，无需再额外调用一次 API。

### WordPress 事件

- `contact.created` / `contact.updated` / `contact.deleted`，对应用户账号
- `content.published` / `content.updated` / `content.unpublished`，对应公开内容
- `comment.created` / `comment.status_changed`，对应访客评论和商品评价（WooCommerce 内部订单备注、pingback 和 trackback 绝不会发出）
- `form.submitted`，对应 **Contact Form 7**、**WPForms**、**Gravity Forms** 和 **Fluent Forms** 的成功提交：只提取有明确类型的邮箱和手机号身份字段以及表单元数据，任意提交字段一律丢弃

## 可靠性：投递发件箱

插件绝不会在页面加载过程中直接把事件打向 Tajo。每个事件先写入本地发件箱表，再由 WP-Cron 投递，并具备：

- 有上限的指数退避（最多 8 次尝试，遵守 `Retry-After`）
- 死信记录，并在管理后台提供一键 **Replay dead letters**
- 保留期限制，让无法访问的端点绝不会囤积个人数据（已投递：7 天；排队中：30 天；死信：最后更新后 30 天）
- 幂等的事件 ID，因此重试和重放绝不会在下游产生重复

如果你的主机禁用了 WP-Cron（`DISABLE_WP_CRON`），请用真正的调度器至少每分钟调用一次 `wp-cron.php`。

## 同意绝不被推断

创建账号、结账、购买以及普通表单提交都**不**会被视为营销同意。内置事件携带的是空的同意列表。要记录明确的同意（例如来自已勾选的订阅邮件复选框），请通过扩展钩子发出：

```php
do_action(
    'tajo_engagement_emit',
    'consent.updated',
    array( 'email' => $email ),
    array( 'policyVersion' => '2026-07' ),
    array(
        array(
            'channel'  => 'email',
            'status'   => 'opt_in',        // or 'opt_out'
            'purpose'  => 'marketing',
            'source'   => 'newsletter_checkbox',
            'evidence' => array( 'formId' => 'newsletter-footer', 'field' => 'marketing_email' ),
        ),
    ),
    gmdate( 'c' )
);
```

同一个钩子也允许任何插件或主题发出自定义事件；所有内容都会经过同一套清洗、发件箱和签名流程。

## 第 3 步：历史数据导入

插件事件覆盖安装之后的一切。对于插件安装之前的历史数据，Tajo 的 WooCommerce REST 连接会导入已有的客户、订单、商品、优惠券、退款和评价，全部在 Tajo 侧用一个 WooCommerce REST API key 完成配置（**WooCommerce → Settings → Advanced → REST API**，读取权限）。详见 [WooCommerce 连接器参考](https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce/)。

## 隐私与 GDPR

- 插件已注册到 WordPress 的 **Tools → Export Personal Data** 和 **Tools → Erase Personal Data**；与某个邮箱匹配、仍保留在发件箱中的事件会在本地被导出或擦除。
- 擦除与投递共享一个 fail-closed 互斥锁，因此在某个负载正在发送途中时，擦除绝不会报告完成。
- 本地擦除只覆盖 WordPress 发件箱；下游数据请在 Tajo 中提交对应的请求。
- 停用插件会暂停投递，但保留配置和排队事件；**删除**插件则会永久移除发件箱、设置、密钥和计划任务。

## 兼容性

- **HPOS**：插件声明兼容 WooCommerce 高性能订单存储，并且只使用 CRUD 对象和公开钩子。
- **WooCommerce Subscriptions**：该扩展启用时，订阅状态变更会被捕获。
- **Multisite**：卸载会清理网络中的每个站点。

## 运维参考

管理员可通过 Application Password 认证使用服务器到服务器的能力发现和发件箱控制：

| 方法 | 路由 | 用途 |
| --- | --- | --- |
| `GET` | `/wp-json/tajo/v1/capabilities` | 插件版本、已识别的适配器、事件清单、发件箱健康状况 |
| `GET` | `/wp-json/tajo/v1/outbox` | 发件箱计数（绝不暴露负载内容） |
| `POST` | `/wp-json/tajo/v1/outbox/process` | 立即处理一批 |
| `POST` | `/wp-json/tajo/v1/outbox/replay` | 重放死信 |

## 故障排查

| 现象 | 原因与处理 |
| --- | --- |
| 事件一直停在 “Queued” | 端点、binding ID 或密钥尚未保存；三者配置齐全之前投递会暂停 |
| 事件一直停在 “Retrying” | 你的主机无法访问 Tajo 端点，或 WP-Cron 没有运行；请检查发件箱表的错误列和你的 cron 配置 |
| 死信不断累积 | 出现了不可重试的错误（通常是 binding ID 或密钥填错）；请先修正配置，再点击 **Replay dead letters** |
| 提示 “Enter a valid HTTPS Tajo webhook endpoint” | 端点必须是 HTTPS，且不能内嵌凭据 |
| 测试事件已投递，但 Tajo 里什么都没有 | 请检查你粘贴的 binding ID 是否来自该端点所属的同一个 Tajo 工作区或连接 |

## 后续步骤

- [WooCommerce 连接器参考](https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce/)：REST 同步、webhook 签名细节、配置项
- [客户同步](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync/)：把 WooCommerce 客户映射到你的记录系统
- 在 Tajo 中使用 `cart.updated`、`order.placed` 和 `order.fulfilled` 事件配置弃购、售后和赢回自动化