申请抢先体验

请填写名字，以及邮箱或手机号。我们会与您联系，提供 Tajo 访问详情。

在本页面

WooCommerce 集成指南

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

Tajo for WooCommerce 插件：在 WordPress 内部捕获实时互动事件（订单、购物车、退款、评价、表单提交），并通过一个持久化、带签名的发件箱把它们投递给 Tajo。
WooCommerce REST 连接：Tajo 读取你店铺的客户、订单、商品、优惠券、退款和评价，用于历史数据导入和持续同步。仅使用 REST 的配置方式见 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 插件

手动安装

# 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 管理后台激活：

进入 Plugins → Installed Plugins
找到 “Tajo for WooCommerce”
点击 Activate

你也可以通过 Plugins → Add New → Upload Plugin 直接上传 zip 包。每个版本都会在 tajo.io/downloads/woocommerce/ 一并发布 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 常量。在这三个值保存之前，事件会安全地排队留在本地发件箱中。

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

点击 Queue test event，再点击 Process now。
投递发件箱表中应显示该事件已投递。
在 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。

同意绝不被推断

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

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 连接器参考。

插件已注册到 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 连接器参考：REST 同步、webhook 签名细节、配置项
客户同步：把 WooCommerce 客户映射到你的记录系统
在 Tajo 中使用 cart.updated、order.placed 和 order.fulfilled 事件配置弃购、售后和赢回自动化