日志（事件）指南

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

---

快速查看摘要

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

---

善用日志记录的原则

• 只记录有意义的交互。请围绕真正具有分析价值的事件进行记录，例如按钮点击、商品查看、支付完成。
• 把参数设置得更具体。例如 button_name: "subscribe_button"像这样具体指定后，就能清楚看出什么带来了成效。
• 以转化漏斗为中心进行设计。测量各阶段的流失率，并将其用于优化 UI 或促销定向。

---

前置要求

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

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

---

点击事件日志记录示例

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

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

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

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

---

元素曝光事件日志记录示例

当特定元素出现在屏幕上时发送曝光事件，就能了解哪些内容更受关注。

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 示例

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

---

事件参数

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

此时 log_name是显示在控制台中的事件名称。控制台的 分析 > 事件 页面中它是区分事件的依据，因此使用意义明确的名称很重要。

例如 product_detail_screen这个页面事件中 product_id, product_category 如果同时发送这些参数，就能确认哪些商品或类别被查看得更多。

事件参数示例

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

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 事件参数示例

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

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 序列化错误等客户端侧错误。