> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 广告主像素

> 在你的网站上跟踪转化和自定义事件，并将其归因到 Kontext 广告的点击。

Kontext 像素是一个面向广告主的小型 JavaScript 标签。把它安装到你的网站上，在你关心的事情发生时（例如购买或注册）触发一个事件，我们就会把这个事件与带来这位访客的广告点击关联起来。

开始之前，请向你的 Kontext 联系人索取**像素令牌**（pixel token）。

## 安装像素

将下面的代码片段粘贴到每个需要跟踪事件的页面的 `<head>` 中，并把 `YOUR_PIXEL_TOKEN` 替换为你的令牌。你也可以通过标签管理器添加，作为在所有页面上运行的自定义 HTML 标签。

```html theme={null}
<!-- Kontext pixel -->
<script>
  !function(k,e){if(k.kontext)return;var f=k.kontext=function(){f.q.push(arguments)};
  f.q=[];f.l=+new Date;var s=e.createElement('script');s.async=1;
  s.src='https://server.megabrain.co/pixel.js';
  var t=e.getElementsByTagName('script')[0];t.parentNode.insertBefore(s,t)}(window,document);
  kontext('init', 'YOUR_PIXEL_TOKEN');
  kontext('track', 'PageView');
</script>
```

页面浏览是由 `PageView` 这一行记录的：像素本身不会自动跟踪任何内容。脚本加载完成之前的调用会进入队列，待脚本就绪后再发送。

## 跟踪事件

在事件发生时，从页面中调用 `kontext('track', ...)`：

```js theme={null}
kontext('track', 'Purchase', { value: 9.99, currency: 'USD', order_id: 'ORDER-123' });
kontext('track', 'Lead');
kontext('track', 'TicketSelected', { match: 'home-opener' });
```

| 参数 | 必填 | 说明 |
| - | - | - |
| `'track'` | 是 | 命令。必须是这个字符串。 |
| 事件名称 | 是 | 由你自行命名，最多 128 个字符。名称按发送时的原样存储，因此每个事件请使用同一种拼写。 |
| 事件参数 | 否 | 一个对象，包含下表中的字段。 |

| 字段 | 类型 | 说明 |
| - | - | - |
| `value` | Number | 以主货币单位表示的金额：`9.99` 表示 9.99 美元。以字符串形式发送的值会被忽略。 |
| `currency` | String | ISO 4217 货币代码，例如 `USD`。 |
| 其他字段 | 任意 | 作为自定义数据随事件存储。单个请求总大小最多 16 KB。 |

### 单页应用

如果你的网站切换页面时不会完整刷新，请在每次路由变化时自行调用 `kontext('track', 'PageView')`。

## 归因方式

1. 用户点击你的广告后，会带着 URL 中的 `kontext_click_id` 参数进入你的网站。这个参数由我们在设置广告活动时配置。你这边的任何重定向都必须保留该参数。
2. 像素读取该参数，并将其存入有效期为 7 天的第一方 Cookie `__kx_clk`。新的点击会替换旧的点击，并重新开始计算 7 天。
3. 只要 Cookie 存在，发送的每个事件都会带上这个点击 ID，因此点击后 7 天内发生的转化会关联到最后一次点击。

没有点击过广告的访客产生的事件同样会被记录，但属于未归因事件。

### 结账页面位于其他域名

Cookie 不会跟随访客到其他主机名，同一网站的其他子域名也是如此。如果你的结账页面在其他地方，请在初始化像素时传入它的主机名：

```js theme={null}
kontext('init', 'YOUR_PIXEL_TOKEN', { checkoutDomain: 'checkout.example.com' });
```

之后，像素会把点击 ID 添加到指向该主机名的链接和表单中。请同时在结账页面上安装像素，以便在那里读取点击 ID。

## 内容安全策略

如果你的网站使用内容安全策略（CSP），请允许我们的主机，并按照你的策略允许其他内联脚本的方式（例如使用 nonce）允许这段内联代码：

```
script-src https://server.megabrain.co;
connect-src https://server.megabrain.co;
```

## 检查安装

打开页面，在浏览器开发者工具中切换到 **Network** 标签页，然后触发一个事件。要测试归因，请在 URL 中加上 `?kontext_click_id=` 和一个测试 UUID，例如 `01977ad2-1f45-799a-9ee7-35540aac4456`。

| 请求 | 响应 | 含义 |
| - | - | - |
| `GET /pixel.js` | `200` | 像素已加载。 |
| `POST /pixel/track` | `204` | 事件已记录。 |
| `POST /pixel/track` | `400` | 事件被拒绝。通常是 URL 中的 `kontext_click_id` 不是有效的 UUID。 |
| `POST /pixel/track` | `401` | 像素令牌有误。 |

如果测试 URL 中的 `kontext_click_id` 无效，请先清除 `__kx_clk` Cookie 再重试。无效值会保留在 Cookie 中，之后的事件也会被拒绝。

## 限制

* 归因依赖第一方 Cookie，因此屏蔽 Cookie 的访客不会被归因。
* 归因只在点击广告的浏览器中有效。访客在手机上点击、在笔记本电脑上购买时不会被归因。
* 广告拦截器可能会拦截像素。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.