> 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/guide/zh/analytics/logging.md).

# 日志（事件）指南

数据日志是提升 Mini App 绩效最重要的工具。记录用户行为和元素曝光，就能找到流失点、提升转化率并优化营销策略。目标不只是简单地堆积数据， **用户在哪些地方停下**和 **对什么有反应**，才是核心。

***

### 摘要快速查看

* 页面跳转日志会自动记录。无需额外设置。
* 点击事件和元素曝光事件如果手动设置，可以分析得更精细。
* SDK 版本 `0.0.26` 及以上即可查看数据。

***

### 善用日志的原则

* 只记录有意义的交互。围绕按钮点击、商品浏览、支付完成等具有实际分析价值的事件进行记录。
* 把参数设置得更具体，例如 `button_name: "subscribe_button"`这样具体指定后，就能更清楚地知道什么带来了成效。
* 围绕转化漏斗进行设计。测量每个阶段的流失率，并用于 UI 改进或促销定向。

***

### 前置要求

* SDK 版本 `0.0.26` 及以上。
* 不提供沙盒或上线准备阶段的数据，只会从实际发布后开始汇总。
* 服务上线后的第二天起，就可以在分析页面查看数据。

在 SDK 中 `Analytics` 对象的使用方法请参考《记录用户行为》文档。

***

### 点击事件日志示例

这是在用户点击按钮时发送事件的基本模式。

```javascript
import { Analytics } from '@apps-in-toss/web-framework';

document.getElementById('myButton').addEventListener('click', function () {
  Analytics.click({ button_name: 'my_button' });
  // 请在这里编写点击后执行的额外动作。
});
```

* `Analytics.click`会记录点击事件。
* `button_name`是用于识别按钮的值。请尽量使用能轻松区分页面和功能的名称。

***

### 元素曝光事件日志示例

当某个元素出现在屏幕上时发送曝光事件，就能知道哪些内容更受关注。

```javascript
import { Analytics } from '@apps-in-toss/web-framework';

const target = document.getElementById('impressionItem');

const observer = new IntersectionObserver(
  ([entry]) => {
    if (entry.isIntersecting) {
      Analytics.impression({ item_id: target.dataset.itemId });
      observer.disconnect();
    }
  },
  { threshold: 0.1 },
);

observer.observe(target);
```

* `IntersectionObserver`会在元素在屏幕上可见度超过 10% 时触发回调。
* `Analytics.impression`会记录曝光事件。
* `item_id`是用于识别已曝光项目的值。

**HTML 示例**

```html
<div id="impressionItem" data-item-id="1234">用于检测曝光的元素
```

***

### 事件参数

事件参数是随事件一并传递的附加信息。即使是同一事件，根据一起发送哪些参数，在控制台中也可以进行更细分的分析。

此时 `log_name`是在控制台中显示的事件名称。控制台里的 **分析 > 事件** 界面中它是区分事件的依据，因此使用含义明确的名称非常重要。

例如 `product_detail_screen`这个页面事件中加入 `product_id`, `product_category` 等参数后，就能确认哪些商品或类别被浏览得更多。

**事件参数示例**

进入商品详情页时，可以将当前查看的商品信息作为参数与页面事件一起传递。

```javascript
import { Analytics } from '@apps-in-toss/web-framework';

Analytics.screen({
  log_name: 'product_detail_screen',
  product_id: 'prod_123',
  product_name: '无线耳机',
  product_category: 'electronics',
  price: 29900,
});
```

* log\_name 是显示在控制台中的事件名。
* 其余值是与该事件一起保存的自定义参数。

**在控制台中如何显示**

像上面那样发送事件后，可以在控制台 > **分析 > 事件** 菜单中查看事件。事件详情页面可以查看以下信息。

* 事件发生趋势（图表）
* 最近发生次数
* 一起发送的参数列表
  * `product_id`
  * `product_name`
  * `product_category`
  * `price`

在参数列表中选择某个特定键后，就能查看该参数的实际值和发生情况。

**Click 事件参数示例**

当用户点击商品购买按钮时，可以把商品信息与点击事件一起传递。

```javascript
import { Analytics } from '@apps-in-toss/web-framework';

Analytics.click({
  log_name: 'purchase_button_click',
  product_id: 'prod_123',
  product_name: '无线耳机',
  product_price: 29900,
  product_category: 'electronics',
});
```

这样发送的事件会在控制台中被汇总为 `purchase_button_click` 事件。借此可以进行如下分析。

* 哪个商品被点击得最多
* 哪些类别的商品会带来转化
* 按价格区间比较点击模式

***

### 在控制台查看数据

日志数据可在管理控制台的 **分析 > 事件** 菜单中查看。该页面可以直接看到点击率、曝光转化率以及主要流失点。

***

### 最佳实践

* 事件名称和参数要标准化。建立团队内的事件命名规则并保持一致使用。例： `category_action_label` 形式
* 不要记录不必要的事件。过多的事件会成为噪音。请以分析目的为标准进行筛选。
* 请将附加属性结构化后发送。例如： `item_id`, `item_category`, `price`, `position` 等内容都包含进去，就能进行更细分的分析。
* 请勿记录个人信息或敏感信息。使用用户标识符时，请遵循匿名化或哈希处理政策。
* 请准备好错误处理和重试逻辑。为应对因网络失败导致事件发送失败的情况，采用队列或重试策略可以减少数据丢失。

***

### 故障排除摘要

* 当项目曝光或点击未被记录时
  1. `Analytics` 请确认调用位置是否存在于 DOM 中。
  2. 请确认是否因为回调注册得太晚而错过了事件。脚本尽量放在顶部。
* 当控制台里看不到数据时
  1. 请确认 SDK 版本是否 `0.0.26` 及以上。
  2. 请确认服务是否已实际发布。沙盒数据不提供。
* 当事件参数为空时
  1. 请确认所发送对象的键名和值是否正确。
  2. 请确认是否不存在客户端错误，例如 JSON 序列化错误。


---

# 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/guide/zh/analytics/logging.md?ask=<question>&goal=<endgoal>
```

`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.