字段口径与 key1 规约

目标：搞清 LogTrack.track 的字段都什么意思、key1 为什么要 JSON.stringify、新老两套口径差在哪。这是新手最容易填错字段的地方。

LogTrack 标准字段表

一条 LogTrack.track(obj, 'click') 的 obj 用这些字段。前 4 个几乎每条都要填，后面按场景填。

哪些字段属于哪类

flowchart LR
    subgraph 固定["每条必填 / 页面级固定"]
        F1["page_name"]
        F2["page_type"]
        F3["page_title"]
        F4["url"]
    end
    subgraph 定位["定位到具体元素"]
        L1["module_name 模块"]
        L2["item_name 项"]
        L3["btn_name 按钮"]
        L4["main_item_id 对象id"]
    end
    subgraph 扩展["扩展细节"]
        E1["key1 = JSON.stringify(...)"]
    end
    style 固定 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style 定位 fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style 扩展 fill:#5a4a6b,color:#fff,stroke:#9a7acc

key1 规约（最重要）

规则

所有扩展字段，统一合并进 key1 一个字段，用 JSON.stringify 包成字符串。不再用 key2、key3。

这是项目维护者定的硬规约（见项目埋点规格文档开头）。

为什么这么做

后台只认 key1 一个扩展位，多个字段挤进去比开 key2/key3 更统一、更好解析。

正确写法

1
2
3
4
5
6
7
8

key1: JSON.stringify({
  user_status: 'member',          // 用户状态
  chapter_id: item.chapterId,     // 章节 id
  is_free: true,                  // 是否免费
  list_type: 'free',              // 列表类型
  current_month: 8,
  jump_url: jumpUrl               // 跳转地址
})

错误写法（别这样）

1
2
3
4
5
6
7
8

// ❌ 用 key2、key3
{ key1: JSON.stringify({user_status:'member'}), key2: chapter_id, key3: is_free }

// ❌ key1 不 stringify
{ key1: { user_status: 'member' } }

// ❌ 把扩展字段平铺到 obj 顶层
{ user_status: 'member', chapter_id: 123, module_name: '课程列表' }

常见 key1 内部字段

事件类型怎么选

flowchart TD
    E["发生了什么"] --> E1{"用户点了?"}
    E1 -- 是 --> C["click<br/>module_name / item_name / btn_name"]
    E1 -- 否 --> E2{"东西展示出来了?"}
    E2 -- 是 --> S["show<br/>module_name / item_name"]
    E2 -- 否 --> E3{"进页面 / 停留?"}
    E3 -- 是 --> P["page<br/>通常只填 page_* 和 key1"]
    style C fill:#6b3a2d,color:#fff,stroke:#d9774a
    style S fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style P fill:#2d4a6b,color:#fff,stroke:#4a90d9

page 和 show 时 btn_name 一般填 - 或空。

新老两套口径（双系统并行时）

在 写法 C 双系统 的 commLog 场景里，同一条数据要发两套，字段名不一样，新手填错就串台。

对照例子（来自阅读诊断报告页）

页面离开时双发：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// ② 新口径：火山
this.$tracker('sndd_hs_page', {
  page_name: '阅读能力诊断和成长规划报告',
  page_id: this.userEvaluationId,
  duration_ms: this.pageStayDuration        // ← 注意是 duration_ms
});

// ① 老口径：神策+自研
LogTrack.track({
  page_name: '阅读能力诊断和成长规划报告',
  page_title: '...',
  page_type: 2,
  url: window.location.href,
  page_id: this.userEvaluationId,
  duration: this.pageStayDuration           // ← 注意是 duration
}, 'page');

page_name / page_type 约定（已知）

新增页面时，page_name 跟产品对齐、全局唯一；活动类页面 page_type 统一填 2。

停留时长单位

• LogTrack 的 duration / expose_duration：毫秒（来自 Date.now() 差值）
• $tracker 的 duration_ms：毫秒（名字里带 _ms 提醒）
• AudioSquare 的 play_duration：秒（audio.currentTime，注意不是毫秒）

填时长字段先确认单位，别把秒当毫秒报。

自检清单（提交前过一遍）

• key1 用了 JSON.stringify，没用 key2/key3
• page_name / page_type / page_title / url 都填了
• click 事件有 module_name + item_name + btn_name
• page / show 的 btn_name 填 - 或空
• 双发场景 duration_ms / duration 别填反
• 埋点代码在业务动作之前，互不影响
• $tracker 事件名带 sndd_hs_ 前缀
• 时长单位确认（毫秒 / 秒）

← 上一篇 埋点点位地图 ｜ 系列完