> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/growth/analytics/toss-ads-pixel.md).
# Toss Ads Pixel 接入
如果你在使用 Toss Ads，可以在 App in Toss 迷你应用中安装 Toss Pixel 来收集转化事件。基于收集到的数据，可以优化广告效果。
{% hint style="info" %}
**Toss Pixel 仅在 Web 环境下运行**
不支持 React Native 环境。
{% endhint %}
### 1. 获取转化追踪代码
请使用收到的账号登录 Toss 广告控制台。
请选择 广告工具 > 转化及追踪联动 菜单。
请生成转化追踪代码。转化追踪代码按广告账号单位发放。
请复制生成的转化追踪代码 ID。
### 2. 安装像素脚本
要使用像素，需要在 HTML 的 `` 区域中添加以下脚本。
```html
```
### 3. 关联事件
需要在事件发生的时点调用像素事件，才能准确收集数据。
{% hint style="info" %}
**请使用一个转化追踪代码**
可用一个转化追踪代码管理所有事件。
{% endhint %}
| 分类 | 事件名称 | 事件标签 |
| ---- | --------- | --------------- |
| 支付 | 支付商品详情页浏览 | PRODUCT\_VIEW |
| | 支付完成 | PURCHASE |
| | 首次购买完成 | FIRST\_PURCHASE |
| | 订阅完成 | SUBSCRIBE |
| 广告 | 应用内广告曝光 | AD\_IMPRESSION |
| 登录 | Toss 登录完成 | SIGNIN |
| 页面浏览 | 转化引导页浏览 | PAGE\_VIEW |
| 自定义 | 自定义事件 | - |
### 4. 按事件的关联方法
**支付**
如果使用应用内支付或 Toss Pay，可以收集支付数据。
**支付商品详情页浏览(`PRODUCT_VIEW`)**
请在浏览商品详情页时调用。
```html
```
**支付完成(`PURCHASE`)**
请在支付正常完成后立即调用。
```html
```
**首次购买完成(`FIRST_PURCHASE`)**
请在用户首次购买完成时调用。
```html
```
**订阅完成(`SUBSCRIBE`)**
请在订阅支付开始时调用。
```html
```
***
**广告**
**应用内广告曝光(`AD_IMPRESSION`)**
在广告曝光时点（例如： `show` 函数调用后立即）调用。
```html
```
***
**登录**
**Toss 登录完成(`SIGNIN`)**
请在 Toss 登录完成时调用。
```html
```
***
**页面浏览**
**转化引导页浏览(`PAGE_VIEW`)**
请在访问特定页面时调用。用于衡量与转化密切相关的页面时很有用。
```html
```
***
**自定义事件**
用于跟踪不属于标准事件的转化。事件名称可以自由定义。
```html
```
***
**自定义属性**
所有事件（标准事件、自定义事件）都可以添加 custom\_param1 \~ custom\_param5。
用于传递标准参数难以表达的附加信息。例如，可以包含活动区分值、促销码、A/B 测试组、流量来源等。
```html
```
***
### 5. 测试
使用 Toss Pixel Helper，可以在本地环境中确认像素事件是否正常运行。
**安装 Toss Pixel Helper**
Toss Pixel Helper 是一款 Chrome 扩展程序，可用于确认安装在网站上的 Toss Pixel 是否正常运行。
* 会自动检测已安装 Toss Pixel 的网站。
* 可实时确认支付、广告、登录等事件是否被收集。
[Toss Pixel Helper Chrome 扩展程序](https://chromewebstore.google.com/detail/toss-pixel-helper/kbbggbgnfmbpjpaieklnbbjfkjkkpcbi?utm_source=item-share-cb) 在页面中 **添加到 Chrome** 点击按钮进行安装。
**在 Chrome 浏览器中确认**
1. 请使用以下命令运行项目。
{% tabs %}
{% tab title="不是 npm。" %}
```sh
npm run dev
```
{% endtab %}
{% tab title="yarn" %}
```sh
yarn dev
```
{% endtab %}
{% tab title="pnpm" %}
```sh
pnpm run dev
```
{% endtab %}
{% endtabs %}
2. 请在 Chrome 浏览器中访问本地服务。
`http://localhost:5173`
3. 请点击浏览器右上角的 Toss Pixel Helper 图标。
4. 如果 Toss Pixel 已正确安装，会显示正在收集的事件列表（PURCHASE、PAGE\_VIEW 等）。还能同时确认事件是否发送以及参数（金额、ID 等）是否包含。
***
### 常见问题
SDK 脚本加载失败会影响迷你应用吗？
不会有影响。若 SDK 加载失败，只会忽略 TossPixel 调用，不会影响迷你应用的正常运行。
在购买完成页刷新后，事件会重复发送吗？
可能会重复发送。需要基于订单 ID 做重复调用拦截处理。
不发送参数也可以吗？
可以。所有参数都是可选的。只调用方法也能正常收集。
不过，如果同时传递参数，可以更准确地分析广告效果。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/growth/analytics/toss-ads-pixel.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.