OpenAI Pixel通过客户事件接入指引

李锐源 · 2026 年7 月 20 日 07:58

一、概述

本文档用于指导 SHOPLINE 商店接入 OpenAI Ads Measurement Pixel。

接入后，当用户点击 ChatGPT 中的广告进入 SHOPLINE 商店时，可向 OpenAI Ads 上报页面浏览、商品浏览、加入购物车、开始结账和购买完成等转化事件，用于衡量广告效果。

OpenAI Pixel官方文档

二、名词解释

名词	通俗解释
ChatGPT 广告	在符合条件的 ChatGPT 场景中展示的付费广告
OpenAI Ads	OpenAI 的广告投放及效果统计系统
SHOPLINE 客户事件	SHOPLINE 在用户浏览、加购、结账或购买时产生的行为通知
埋点	监听客户事件、整理数据并发送给第三方平台的代码及过程
OpenAI Ads Pixel	安装在商店中的浏览器事件上报工具
Pixel ID	商家在 OpenAI Ads 中的数据来源标识
转化	页面浏览、商品浏览、加入购物车、开始结账或购买等目标行为

三、工作原理

用户点击 ChatGPT 广告
        ↓
进入 SHOPLINE 商店
        ↓
浏览商品、加购、结账或购买
        ↓
SHOPLINE 产生客户事件
        ↓
自定义像素代码监听并转换事件
        ↓
OpenAI Ads Pixel 上报转化
        ↓
OpenAI Ads 统计广告效果

四、兼容主题版本

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

五、事件对应关系

用户行为	SHOPLINE 客户事件	OpenAI 标准事件
浏览页面	`page_viewed`	`page_viewed`
浏览商品	`product_viewed`	`contents_viewed`
加入购物车	`product_added_to_cart`	`items_added`
开始结账	`checkout_started`	`checkout_started`
完成购买	`checkout_completed`	`order_created`

OpenAI 的事件名并不总是与 SHOPLINE 相同。接入代码会完成事件名称及数据格式的转换。

六、数据传递规则

本指引中的商品、价格、数量、币种、订单号和页面信息均从 SHOPLINE 客户事件中动态读取，不使用固定业务值。

amount 必须是整数，并使用对应币种的 ISO 4217 最小货币单位。例如 USD 12.99 传 1299
传递 amount 时必须同时传递 currency。
quantity 必须是整数。

七、操作流程

1. 获取 Pixel ID

前往 OpenAI Ads Manager 的 Conversions 页面创建或查看 Pixel ID。

后续代码中的 <YOUR-PIXEL-ID> 必须替换为商家自己的 Pixel ID。

2. 创建自定义像素代码

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

3. 安装 Pixel 初始化代码

以下初始化代码必须安装。事件订阅代码不要一次性全部复制，应根据实际需要，从后文选择对应事件添加在初始化代码下方。

(function (w, d, s, u) {
  if (w.oaiq) return;
  var q = function () {
    q.q.push(arguments);
  };
  q.q = [];
  w.oaiq = q;
  var js = d.createElement(s);
  js.async = true;
  js.src = u;
  var f = d.getElementsByTagName(s)[0];
  f.parentNode.insertBefore(js, f);
})(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");

oaiq("init", {
  pixelId: "<YOUR-PIXEL-ID>"
});

4. 添加金额转换方法

OpenAI 的 amount 必须使用币种的最小货币单位整数。以下公共方法用于转换事件总金额和商品单价，只需在 Pixel 初始化代码下方添加一次。

// 将 SHOPLINE 金额转换为 OpenAI 要求的最小货币单位整数。
// 例如 USD 12.99 转为 1299，JPY 1299 转为 1299，KWD 12.345 转为 12345。
const toMinorUnit = (value, currency) => {
  const zeroDecimal = [
    "BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW",
    "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF"
  ];
  const threeDecimal = ["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"];
  const fourDecimal = ["CLF", "UYW"];

  let exponent = 2;
  if (zeroDecimal.includes(currency)) exponent = 0;
  if (threeDecimal.includes(currency)) exponent = 3;
  if (fourDecimal.includes(currency)) exponent = 4;

  return Math.round(value * Math.pow(10, exponent));
};

5. 按需添加事件代码

每个 SHOPLINE 事件的 event.data 结构不同，因此每段订阅代码独立处理自己的字段。开发者只需复制需要上报的事件，不要用一套字段读取逻辑处理全部事件。

5.1 页面浏览 `page_viewed`

SHOPLINE 页面浏览事件的 event.data 结构如下：

{
  title: string;
  url: string;
  path: string;
}

页面浏览事件使用 path 标识当前页面，使用 title 作为页面名称。url 不需要放入 contents[]，OpenAI Pixel 会自动记录页面来源。

analytics.subscribe("page_viewed", (event) => {
  const data = event.data || {};

  oaiq("measure", "page_viewed", {
    type: "contents",
    contents: [
      {
        id: data.path,
        name: data.title,
        content_type: "page"
      }
    ]
  });
});

5.2 商品浏览 `product_viewed`

SHOPLINE 商品浏览事件的 event.data 结构如下：

{
  spuId: string;
  skuId: string;
  skuItemNo: string;
  currency: string;
  title: string;
  variant: string;
  price: number;
  category: string;
  collectionId: string;
  collectionName: string;
}

商品浏览使用 skuId 标识当前浏览的商品，使用 title 作为商品名称。

analytics.subscribe("product_viewed", (event) => {
  const data = event.data || {};

  oaiq("measure", "contents_viewed", {
    type: "contents",
    contents: [
      {
        id: data.skuId,
        name: data.title,
        content_type: "product"
      }
    ]
  });
});

5.3 加入购物车 `product_added_to_cart`

SHOPLINE 加入购物车事件的 event.data 结构如下：

{
  cartId: string;
  value: number;
  currency: string;
  list: {
    spuId: string;
    skuId: string;
    skuItemNo: string;
    title: string;
    variant: string;
    price: number;
    quantity: number;
    category: string;
  }[];
}

加入购物车使用 value 作为本次加入商品的总金额，并将 list 转换为 OpenAI 的商品列表。

analytics.subscribe("product_added_to_cart", (event) => {
  const data = event.data || {};
  const contents = (data.list || []).map((item) => ({
    id: item.skuId,
    name: item.title,
    content_type: "product",
    quantity: item.quantity,
    amount: toMinorUnit(item.price, data.currency),
    currency: data.currency
  }));

  oaiq("measure", "items_added", {
    type: "contents",
    amount: toMinorUnit(data.value, data.currency),
    currency: data.currency,
    contents
  });
});

5.4 开始结账 `checkout_started`

SHOPLINE 开始结账事件的 event.data 结构如下：

{
  value: number;
  currency: string;
  list: {
    spuId: string;
    skuId: string;
    skuItemNo: string;
    title: string;
    variant: string;
    price: number;
    quantity: number;
    category: string;
  }[];
}

开始结账使用 value 作为结账总金额，并将完整的 list 转换为 OpenAI 的商品列表。

analytics.subscribe("checkout_started", (event) => {
  const data = event.data || {};
  const contents = (data.list || []).map((item) => ({
    id: item.skuId,
    name: item.title,
    content_type: "product",
    quantity: item.quantity,
    amount: toMinorUnit(item.price, data.currency),
    currency: data.currency
  }));

  oaiq("measure", "checkout_started", {
    type: "contents",
    amount: toMinorUnit(data.value, data.currency),
    currency: data.currency,
    contents
  });
});

5.5 购买完成 `checkout_completed`

SHOPLINE 购买完成事件的 event.data 结构如下：

{
  orderSeq: string;
  appOrderSeq: string;
  value: number;
  shippingAmount: number;
  taxAmount: number;
  coupon?: string;
  currency: string;
  list: {
    spuId: string;
    skuId: string;
    skuItemNo: string;
    title: string;
    variant: string;
    price: number;
    quantity: number;
    category: string;
  }[];
}

购买完成应传订单总金额、币种和完整商品列表。orderSeq 可作为 event_id

analytics.subscribe("checkout_completed", (event) => {
  const data = event.data || {};
  const contents = (data.list || []).map((item) => ({
    id: item.skuId,
    name: item.title,
    content_type: "product",
    quantity: item.quantity,
    amount: toMinorUnit(item.price, data.currency),
    currency: data.currency
  }));

  oaiq(
    "measure",
    "order_created",
    {
      type: "contents",
      amount: toMinorUnit(data.value, data.currency),
      currency: data.currency,
      contents
    },
    {
      event_id: data.orderSeq
    }
  );
});

6. 保存并连接

添加代码后点击「保存」，再点击「连接」。