Taboola Pixel 客户事件接入指引

李锐源 · 2026 年8 月 13 日 06:48

一、概述

本文档用于指导 SHOPLINE 商店通过「客户事件」接入 Taboola Pixel。
接入后，当用户进入 SHOPLINE 商店并浏览商品、加入购物车、开始结账或完成购买时，可向 Taboola 上报对应事件，用于衡量广告效果。

Taboola Pixel 官方文档：

二、名词解释

名词	通俗解释
SHOPLINE 客户事件	SHOPLINE 在用户浏览、加购、结账或购买时产生的行为通知
埋点	监听客户事件并向第三方平台发送数据的代码及过程
Taboola Pixel	安装在商店中、用于向 Taboola 上报页面浏览和转化事件的追踪工具
Account ID	Taboola 为广告账户分配的识别编号，用于将事件归属到对应账户
转化	商品浏览、加入购物车、开始结账或完成购买等目标行为

三、工作原理

用户进入 SHOPLINE 商店
        ↓
浏览商品、加购、结账或购买
        ↓
SHOPLINE 产生客户事件
        ↓
自定义像素代码监听并转换事件
        ↓
Taboola Pixel 上报事件
        ↓
Realize 使用同名 Event Name 的转化规则识别事件
        ↓
Taboola 统计广告效果

四、兼容主题版本

SHOPLINE Online Store 1.0 / 2.0 / 2.1 / 3.0 主题。

五、事件对应关系

用户行为	SHOPLINE 客户事件	Taboola Event Name
浏览页面	Base Pixel 加载	`page_view`
浏览商品	`product_viewed`	`product_view`
加入购物车	`product_added_to_cart`	`add_to_cart`
开始结账	`checkout_started`	`start_checkout`
完成购买	`checkout_completed`	`make_purchase`
浏览购物车	`cart_viewed`	`cart_view`
浏览商品列表	`collection_viewed`	`collection_view`
提交搜索	`search_submitted`	`search_submitted`

Event Name 可以在 Realize 中编辑，但代码中的 name 必须与后台最终保存的 Event Name 完全一致。本文档使用 Taboola 官方指引中的事件名。

六、操作流程

1. 获取 Account ID

在 Taboola Ads 后台查看需要接入的 Account ID。

2. 在 Taboola Realize 创建事件型转化

安装代码前，需要在 Taboola Realize 中为需要上报的每个事件创建对应的转化规则：

选择用于追踪转化的 Taboola 账户。
进入 Tracking，点击 + New Conversion。
选择 Create conversions manually，再点击 Continue。
填写便于识别的 Conversion Name。该名称只在后台展示，不需要与代码一致。
Conversion Type 选择 EVENT。
按照「事件对应关系」选择 Category，并确认 Event Name。
保存转化规则。

仅在 SHOPLINE 中执行 _tfa.push() 不代表已经定义转化。如果 Realize 中没有同名 Event Name 的转化规则，Taboola 可能在 Active Events 中收到事件，但不会将其计入对应转化。

动态参数设置

Taboola Pixel 支持以下动态转化参数：

Realize 选项	Pixel 参数	SHOPLINE 购买完成字段	用途
Value	`revenue`	`event.data.value`	订单总金额
Currency	`currency`	`event.data.currency`	订单币种
Order ID	`orderid`	`event.data.orderSeq`	订单号
Quantity	`quantity`	`event.data.list[].quantity` 求和	订单商品总数量

建议只为 make_purchase 选择这四项动态参数。对于浏览、搜索、加购和开始结账等事件，本指引只上报事件次数，不上报动态价值，如有需要，可自行在代码中上报对应的动态参数。

Taboola Pixel 没有定义 SKU ID、SPU ID、商品名称或商品列表等动态参数，因此 SHOPLINE 的 event.data.list 不能作为商品明细数组上报。本指引仅将其用于计算 quantity。

3. 创建 SHOPLINE 自定义像素代码

在 SHOPLINE 后台的「客户事件」中，点击「添加自定义像素代码」，创建像素代码。

4. 安装 Taboola Base Pixel

将下方 Taboola 官方 Base Pixel 代码完整复制到自定义像素代码中。该初始化代码保持官方原样，不要改写加载方式。

代码中共有两处 <account_id>，必须全部替换为商家自己的 Taboola Account ID。例如 Account ID 为 1234567 时，id: <account_id> 应替换为 id: 1234567。

window._tfa = window._tfa || [];
window._tfa.push({notify: 'event', name: 'page_view', id: <account_id>});
!function (t, f, a, x) {
        if (!document.getElementById(x)) {
        t.async = 1;t.src = a;t.id=x;f.parentNode.insertBefore(t, f);
        }
}(document.createElement('script'),
document.getElementsByTagName('script')[0],
'//cdn.taboola.com/libtrc/unip/<account_id>/tfa.js',
'tb_tfa_script');

5. 按需添加事件代码

从下文选择需要上报的事件，将对应代码添加在 Base Pixel 下方。代码中的 YOUR_ACCOUNT_ID 必须替换为与 Base Pixel 相同的 Taboola Account ID，保持数字格式，不要加引号。

除购买完成事件外，以下示例只上报事件是否发生。event.data 中未明确写入 _tfa.push() 的字段不会被自动发送给 Taboola。

5.1 商品浏览 `product_viewed`

SHOPLINE 商品浏览事件的 event.data 结构说明：

{
  spuId: string; // SPU ID
  skuId: string; // SKU ID
  skuItemNo: string; // SKU 商品编号
  currency: string; // 币种
  title: string; // 商品标题
  variant: string; // 商品规格
  price: number; // 商品价格
  category: string; // 商品分类
  collectionId: string; // 商品集 ID
  collectionName: string; // 商品集名称
}

添加以下代码：

analytics.subscribe("product_viewed", (event) => {
  _tfa.push({ notify: "event", name: "product_view", id: YOUR_ACCOUNT_ID });
});

5.2 加入购物车 `product_added_to_cart`

SHOPLINE 加入购物车事件的 event.data 结构说明：

{
  cartId: string; // 购物车 ID
  value: number; // 本次加入商品的总金额
  currency: string; // 币种
  list: { // 本次加入购物车的商品列表
    spuId: string; // SPU ID
    skuId: string; // SKU ID
    skuItemNo: string; // SKU 商品编号
    title: string; // 商品标题
    variant: string; // 商品规格
    price: number; // 商品单价
    quantity: number; // 商品数量
    category: string; // 商品分类
  }[];
}

添加以下代码：

analytics.subscribe("product_added_to_cart", (event) => {
  _tfa.push({ notify: "event", name: "add_to_cart", id: YOUR_ACCOUNT_ID });
});

5.3 开始结账 `checkout_started`

SHOPLINE 开始结账事件的 event.data 结构说明：

{
  value: number; // 结账商品总金额
  currency: string; // 币种
  list: { // 本次结账的商品列表
    spuId: string; // SPU ID
    skuId: string; // SKU ID
    skuItemNo: string; // SKU 商品编号
    title: string; // 商品标题
    variant: string; // 商品规格
    price: number; // 商品单价
    quantity: number; // 商品数量
    category: string; // 商品分类
  }[];
}

添加以下代码：

analytics.subscribe("checkout_started", (event) => {
  _tfa.push({ notify: "event", name: "start_checkout", id: YOUR_ACCOUNT_ID });
});

5.4 完成购买 `checkout_completed`

SHOPLINE 完成购买事件的 event.data 结构说明：

{
  orderSeq: string; // SHOPLINE 订单号
  appOrderSeq: string; // 应用订单号
  value: number; // 订单总金额
  shippingAmount: number; // 运费
  taxAmount: number; // 税费
  coupon?: string; // 优惠码，未使用时可能不存在
  currency: string; // 币种
  list: { // 订单商品列表
    spuId: string; // SPU ID
    skuId: string; // SKU ID
    skuItemNo: string; // SKU 商品编号
    title: string; // 商品标题
    variant: string; // 商品规格
    price: number; // 商品单价
    quantity: number; // 商品数量
    category: string; // 商品分类
  }[];
}

添加以下代码：

analytics.subscribe("checkout_completed", (event) => {
  const data = event.data;

  // Taboola 的 Quantity 是订单商品总数量，不支持上报完整商品列表。
  const quantity = (data.list || []).reduce(
    (total, item) => total + item.quantity,
    0
  );

  _tfa.push({
    notify: "event",
    name: "make_purchase",
    id: YOUR_ACCOUNT_ID,
    revenue: data.value,
    currency: data.currency,
    orderid: data.orderSeq,
    quantity
  });
});

5.5 购物车浏览 `cart_viewed`

添加以下代码：

analytics.subscribe("cart_viewed", (event) => {
  _tfa.push({ notify: "event", name: "cart_view", id: YOUR_ACCOUNT_ID });
});

5.6 商品列表浏览 `collection_viewed`

SHOPLINE 商品列表浏览事件的 event.data 结构说明：

{
  collectionType: ProductListCollectionType; // 商品列表类型
  collectionId: string; // 商品集 ID
  collectionName: string; // 商品集名称
  currency: string; // 币种
  list: { // 当前商品列表
    spuId: string; // SPU ID
    skuId: string; // SKU ID
    skuItemNo: string; // SKU 商品编号
    title: string; // 商品标题
    price: number; // 商品价格
    category: string; // 商品分类
  }[];
}

添加以下代码：

analytics.subscribe("collection_viewed", (event) => {
  _tfa.push({ notify: "event", name: "collection_view", id: YOUR_ACCOUNT_ID });
});

5.7 提交搜索 `search_submitted`

添加以下代码：

analytics.subscribe("search_submitted", (event) => {
  _tfa.push({ notify: "event", name: "search_submitted", id: YOUR_ACCOUNT_ID });
});

6. 完整事件代码示例

注意替换代码中的<account_id> 与 YOUR_ACCOUNT_ID

window._tfa = window._tfa || [];
window._tfa.push({notify: 'event', name: 'page_view', id: <account_id>});
!function (t, f, a, x) {
        if (!document.getElementById(x)) {
        t.async = 1;t.src = a;t.id=x;f.parentNode.insertBefore(t, f);
        }
}(document.createElement('script'),
document.getElementsByTagName('script')[0],
'//cdn.taboola.com/libtrc/unip/<account_id>/tfa.js',
'tb_tfa_script');
analytics.subscribe("product_viewed", (event) => {
  _tfa.push({ notify: "event", name: "product_view", id: YOUR_ACCOUNT_ID });
});
analytics.subscribe("product_added_to_cart", (event) => {
  _tfa.push({ notify: "event", name: "add_to_cart", id: YOUR_ACCOUNT_ID });
});
analytics.subscribe("checkout_started", (event) => {
  _tfa.push({ notify: "event", name: "start_checkout", id: YOUR_ACCOUNT_ID });
});
analytics.subscribe("checkout_completed", (event) => {
  const data = event.data;

  // Taboola 的 Quantity 是订单商品总数量，不支持上报完整商品列表。
  const quantity = (data.list || []).reduce(
    (total, item) => total + item.quantity,
    0
  );

  _tfa.push({
    notify: "event",
    name: "make_purchase",
    id: YOUR_ACCOUNT_ID,
    revenue: data.value,
    currency: data.currency,
    orderid: data.orderSeq,
    quantity
  });
});
analytics.subscribe("cart_viewed", (event) => {
  _tfa.push({ notify: "event", name: "cart_view", id: YOUR_ACCOUNT_ID });
});
analytics.subscribe("collection_viewed", (event) => {
  _tfa.push({ notify: "event", name: "collection_view", id: YOUR_ACCOUNT_ID });
});
analytics.subscribe("search_submitted", (event) => {
  _tfa.push({ notify: "event", name: "search_submitted", id: YOUR_ACCOUNT_ID });
});

7. 保存并连接

所需事件代码添加完成后，点击「保存」，再点击「连接」。

Taboola Pixel 客户事件接入指引

一、概述

二、名词解释

三、工作原理

四、兼容主题版本

五、事件对应关系

六、操作流程

1. 获取 Account ID

2. 在 Taboola Realize 创建事件型转化

动态参数设置

3. 创建 SHOPLINE 自定义像素代码

4. 安装 Taboola Base Pixel

5. 按需添加事件代码

5.1 商品浏览 product_viewed

5.2 加入购物车 product_added_to_cart

5.3 开始结账 checkout_started

5.4 完成购买 checkout_completed

5.5 购物车浏览 cart_viewed

5.6 商品列表浏览 collection_viewed

5.7 提交搜索 search_submitted

6. 完整事件代码示例

7. 保存并连接

5.1 商品浏览 `product_viewed`

5.2 加入购物车 `product_added_to_cart`

5.3 开始结账 `checkout_started`

5.4 完成购买 `checkout_completed`

5.5 购物车浏览 `cart_viewed`

5.6 商品列表浏览 `collection_viewed`

5.7 提交搜索 `search_submitted`