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

# 日志（事件）指南

数据日志记录是提升迷你应用成效最重要的工具。记录用户行为和元素曝光，可以找到流失点、提升转化率，并优化营销策略。它的目的不只是堆积数据，而是 **用户在哪里停下**以及 **对什么作出反应**，关键在于把这些弄清楚。

***

### 快速查看摘要

* 页面跳转日志会自动记录，无需额外设置。
* 点击事件和元素曝光事件如果手动设置，可以分析得更精细。
* 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.