前端工程化-埋点 on acye's blog

生产环境推荐实践

Sat, 22 Aug 2026 15:00:00 +0000

生产环境推荐实践

目标：教学 demo 用本地 console 模拟就够了，但真要上线，研发该怎么做。这篇讲清楚：生产为什么接真实 SDK、好处是什么、前端和后端各自的责任、前后端怎么对齐口径。

面向：要把埋点从"能跑"推到"能分析、能信"的研发同学。

教学模拟 vs 生产，差在哪

维度	本地 console 模拟（demo）	生产真实接入
数据去哪	控制台 / 页面面板	埋点后台（神策 / 火山 / 自建）
能分析吗	不能，只是看一眼	能出看板、漏斗、留存、路径
用户身份	无	uuid / user_pid，跨端跨会话识别
离开页送达	模拟 flush	真实网络，可能丢 → 要 `sendBeacon` 兜底
环境隔离	开关切换	多套 appId / 域名 / 密钥
采样/限流	无	高流量场景必须

结论：模拟只验证"机制对不对"；生产要解决"数据准不准、全不全、能不能用"。

生产为什么要接真实 SDK（好处）

flowchart LR
    subgraph SDK能力["成熟埋点 SDK 白送的能力"]
        A1["全埋点 PV<br/>路由切换自动记"]
        A2["用户唯一标识<br/>uuid 跨端跨会话"]
        A3["会话 & 来源链路<br/>refer_page_name"]
        A4["热力图 / 圈选<br/>运营自己圈元素分析"]
        A5["AB 实验<br/>分桶联动"]
        A6["设备/环境采集<br/>机型/版本/网络"]
        A7["离开页送达<br/>sendBeacon/beacon API"]
        A8["采样 & 限流<br/>扛高并发"]
    end
    SDK能力 --> B["业务收益"]
    B --> B1["产品看漏斗/留存决策"]
    B --> B2["运营圈选优化布局"]
    B --> B3["数据团队建模分析"]

    style SDK能力 fill:#1e2a3a,color:#fff,stroke:#4a90d9
    style B fill:#2d4a6b,color:#fff,stroke:#4a90d9

一句话：自研上报容易，但"用户是谁、从哪来、看了多久、丢没丢"这些工程问题，成熟 SDK 已经踩过坑。生产接 SDK 是站在它肩膀上，不是重复造轮子。

生产数据流（前端 → 后端 → 看板）

flowchart LR
    F["前端 H5"] -->|"1 SDK 自动/手动上报"| G["埋点网关<br/>(网关层)"]
    G -->|"2 字段清洗/补全"| Q["消息队列 Kafka"]
    Q -->|"3 落库"| S["数仓 / OLAP"]
    S --> B1["神策/火山看板"]
    S --> B2["BI 报表"]
    S --> B3["数据建模"]
    F -.->|"sendBeacon 兜底<br/>关页面/切后台"| G
    style F fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style G fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style Q fill:#5a4a6b,color:#fff,stroke:#9a7acc
    style S fill:#6b3a2d,color:#fff,stroke:#d9774a

前端研发职责

SDK 接入与初始化

在入口文件创建实例、传入 appId / 上报域名 / 环境开关
环境隔离：生产 / 测试 / sim 用不同 appId，别把测试数据灌进生产
enableOutAPP 之类开关按需配，明确"App 内外行为差异"

公共字段与开关统一管理

page_name / page_type / url 等公共字段抽成常量或封装函数，别散落各页面
key1 一律 JSON.stringify，不开 key2/key3（见字段口径）

停留时长与离开页兜底

心跳定时上报 + visibilitychange 暂停/恢复 + beforeDestroy flush（见写法 G 心跳）
生产关键：离开页上报优先用 navigator.sendBeacon()，比普通 XHR 更能在页面关闭时送达
hidden 与 pagehide 监听注意去重，避免同一次离开报两遍

不阻断业务

埋点调用排在业务动作之前，且 try/catch 包裹或 SDK 内部吞异常
埋点挂了，用户操作必须照常

密钥与脱敏（开源/公开仓库时）

appId、上报域名、密钥走环境变量（.env.*），不硬编码进源码
开源仓库用占位值 + 文档说明，真实密钥只在 CI/部署注入
用户敏感信息（手机号、token）绝不进埋点字段，key1 里只放分析需要的业务 id

灰度与采样

新埋点先灰度小流量验证数据是否符合预期，再全量
高频事件（滚动、播放进度）考虑采样，别把网关打爆

自测

开 debug 开关，控制台确认每条事件字段完整、单位正确
对照需求文档逐条核对"该报的场景都报了"
新老口径双发时，确认 duration_ms / duration 没填反

后端研发职责

接收网关

提供稳定上报接口，支持高并发；前端 SDK 直连或经业务网关转发
鉴权：校验来源合法性，防伪造刷量

字段清洗与补全

前端缺的公共字段（IP、UA、地域、时间戳）在网关/消费侧补全
异常字段过滤：page_name 为空、key1 非法 JSON 等落"脏数据表"告警，别污染主表

新老口径映射

前端双发（$tracker 的 duration_ms vs LogTrack 的 duration）在后端做归一映射，落库统一字段名
维护一份"事件名 → 业务含义"字典表，供数据同学查

去重与幂等

同一次离开可能因 hidden + pagehide 重复上报 → 后端按 (session_id, event, timestamp 窗口) 去重
上报请求支持幂等键，防网络重试导致重复

监控与告警

上报量突增/突降告警（可能是 SDK 加载失败或页面白屏）
字段缺失率、脏数据率纳入监控
离开页事件送达率单独看（sendBeacon 失败兜底统计）

数据落库与查询

落数仓 / OLAP，供神策、火山、自建 BI 查询
大表分区按天，冷热分层

前后端协作口径

sequenceDiagram
    participant FE as 前端
    participant BE as 后端
    participant DA as 数据/产品
    DA->>FE: 提埋点需求表(事件+字段)
    FE->>FE: 按口径实现+自测(debug)
    FE->>BE: 确认事件名/字段/单位
    BE->>BE: 网关接收+清洗+落库
    FE->>BE: 灰度验证数据
    BE->>DA: 看板/漏斗可用
    DA->>FE: 反馈口径问题/补埋

统一字典：事件名、字段名、单位、枚举值前后端共用一份文档（项目对应埋点规格文档 / 报告页埋点规格文档）
单位先行：时长是毫秒还是秒，需求阶段就定死，别等数据对不上才查
变更走流程：改字段名 / 加字段要同步更新字典 + 通知后端做映射，别前端单方面改

生产自检清单

前端：

appId / 密钥走 env，未硬编码
公共字段抽封装，key1 已 stringify
离开页用 sendBeacon，hidden/pagehide 去重
埋点 try/catch，不阻断业务
debug 自测字段完整、单位正确
新埋点灰度后再全量

后端：

网关鉴权 + 限流
字段补全 + 脏数据过滤
新老口径归一映射
去重 / 幂等
上报量 / 送达率 / 脏数据率监控告警
事件字典表维护

← 字段口径与 key1 规约｜系列完 · demo 见 demo

字段口径与 key1 规约

Sat, 22 Aug 2026 14:00:00 +0000

字段口径与 key1 规约

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

LogTrack 标准字段表

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

字段	类型	含义	示例
`page_name`	string	页面中文名（业务定，全局唯一）	`少年闻天下`
`page_type`	number	页面类型，本项目活动页统一 `2`	`2`
`page_title`	string	页面标题，一般同 page_name	`少年闻天下`
`url`	string	当前页面地址	`window.location.href`
`main_item_id`	string	主对象 id（点的是哪个课程 / 卡片）	`item.chapterId`
`module_name`	string	页面内模块名	`课程列表`、`导航栏`
`item_name`	string	模块内项名	`列表项`、`返回按钮`
`btn_name`	string	按钮文案	`立即订阅`、`返回`
`key1`	string	所有扩展细节，JSON 字符串	`JSON.stringify({user_status, ...})`

哪些字段属于哪类

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 更统一、更好解析。

正确写法

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

错误写法（别这样）

// ❌ 用 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 内部字段

字段	含义	常见值
`user_status`	用户状态	`normal` / `expired_member` / `member`
`current_tab`	当前 tab	`knowledge` / `material` / `essay`
`list_type`	列表类型	`free` / `all` / `member`
`chapter_id` / `course_id`	内容 id	-
`is_free` / `is_locked`	是否免费 / 锁定	`true` / `false`
`current_month` / `current_year`	月份 / 年份	`8` / `2026`
`jump_url`	跳转地址	-
`duration`	停留时长（毫秒）	`pageStayDuration`
`list_data`	列表批量数据	`[{id,title,publishTime}]`
`list_count` / `page_index`	列表条数 / 页码	-

事件类型怎么选

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`	mounted / created 后 / 停留心跳	page_* + key1(duration)
`show`	列表加载完 / 弹窗打开 / Banner 有数据	module_name + item_name + key1
`click`	用户点击	module_name + item_name + btn_name + key1

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

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

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

	② $tracker（火山，新口径）	① LogTrack（神策+自研，老口径）
调用	`this.$tracker('sndd_hs_xxx', payload)`	`LogTrack.track(payload, 'page')`
事件标识	事件名 `sndd_hs_page` / `sndd_hs_show` / `sndd_hs_click`	事件类型 `page` / `show` / `click`
页面停留时长字段	`duration_ms`	`duration`
模块曝光时长字段	`duration_ms`	`expose_duration`
页面名字段	`page_name`	`page_name` + `page_title` + `page_type`
是否带 url	自动补 `window.location.href`	需手填 `url`

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

页面离开时双发：

// ② 新口径：火山
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	newsSubscription
知识卡	2	knowledgeCard/index
知识卡详情	2	knowledgeCard/detail
阅读营给孩子的一封信	2	emailReport
阅读能力诊断和成长规划报告	-	readingDiagnosisReport
测评报告	-	stageEvaluationReport
专题详情页	2	EventComponent（运营活动）

新增页面时，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_ 前缀
时长单位确认（毫秒 / 秒）

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

埋点点位地图

Sat, 22 Aug 2026 13:00:00 +0000

埋点点位地图

目标：“哪些地方埋了点”。按业务模块整理，给新手一张寻宝图。

统计口径：LogTrack.track 调用点 ~40 个文件、$tracker 调用点 ~20 个文件、v-log 指令 ~13 个组件、$timeTrack 2 处。下面按模块归类。

模块全景

flowchart TB
    subgraph 内容消费["内容 / 课程消费"]
        M1["课程详情<br/>courseDetail<br/>newCourseDetail"]
        M2["课程视频<br/>courseVideo"]
        M3["音频播放<br/>AudioSquare"]
        M4["读书 newBook"]
    end
    subgraph 报告页["报告页（埋点最复杂）"]
        R1["阅读信件<br/>emailReport"]
        R2["阅读能力诊断<br/>readingDiagnosisReport"]
        R3["阶段测评报告<br/>stageEvaluationReport"]
    end
    subgraph 运营活动["运营活动"]
        A1["活动页框架<br/>_H5ActivityView"]
        A2["operateActivityV2"]
        A3["homeActivity"]
    end
    subgraph 新闻知识["少年闻天下 / 知识卡"]
        N1["newsSubscription"]
        N2["knowledgeCard"]
    end
    subgraph 用户增长["用户增长"]
        U1["signinActivity 签到"]
        U2["fission 裂变"]
        U3["inviteCoupon 邀请券"]
        U4["medalShare 勋章"]
    end
    subgraph 其它["其它"]
        O1["App.vue 全局"]
        O2["h5Reg 注册"]
        O3["telCodeInput 验证码"]
    end

    style 报告页 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style 运营活动 fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style 新闻知识 fill:#5a4a6b,color:#fff,stroke:#9a7acc

全局入口

位置	写法	点位
App 根组件	F autoTrack	`LogTrack.track({}, 'autoTrack', true, routes)` 全路由自动曝光
App 根组件	$timeTrack	`appCreated`、`appMounted` 性能计时
入口 main.js	初始化	`logTrackFactory` → `$tracker`（火山实例）
公共导入模块	初始化	`LogTrack.config().init()`、`$timeTrack` 注册

报告页模块（埋点最复杂）

这三个页面是全项目埋点最重的，都用了 C 双系统并行 + G 停留时长心跳，部分还带模块曝光时长。

页面	写法	事件	说明
阅读信件报告页	C + G	`sndd_hs_page`、`sndd_hs_bottom_show`、`page`	心跳 3s、`visibilitychange`、滚动到底上报
阅读诊断报告页	C + G	`sndd_hs_page/show`、`page/show`	11 个模块曝光时长，详见报告页埋点规格文档
阶段测评报告页	C + G	`sndd_hs_page/show/click`	4 模块曝光，见报告页埋点规格文档
简化版报告页	C	`sndd_hs_*`	简化版报告

已有规格文档：报告页埋点规格文档（讲透时长 / 曝光 / 离开时机，强烈推荐先读）。

少年闻天下 / 知识卡模块

已有规格文档：项目埋点规格文档。落地代码：

页面	写法	调用点数	事件
少年闻天下订阅页	A 直接调	23	page / show / click 全覆盖
知识卡页面	B this.track 封装	~9	page / show / click
知识卡详情页	B this.track 封装	~3	page / click

事件覆盖：页面曝光、课程列表批量曝光、返回、Tab 切换、订阅 / 续费、课程项点击、月份 / 年份筛选、百宝箱、推荐课程、续费弹窗、Banner 等。详见项目埋点规格文档。

课程 / 内容消费模块

页面	写法	点位
课程详情页	A + D v-log	`ev__course_detail_play` 播放点击
新版课程详情页	A + D evLogTrack	课程详情曝光 / 播放
课程视频页	A + D evLogTrack	视频页曝光 / 播放
课程计划页	A	课程计划
音频广场组件	② $tracker	`sndd_hs_knowledge_publishing_course_play` 音频播放时长
视频组件	A	`LogTrack.track(this.evLogTrack, 'page')`
音频组件	D v-log	`v-log:click.ev__click`
读书页	A + D evLogTrack	读书页
免费音频课页	A	免费音频课

音频 / 视频播放时长统一走 ② $tracker（火山），因为要和 App 原生播放埋点对齐。

运营活动模块

页面	写法	点位
活动页事件组件	E 配置驱动	按后台配置 `eventType` 自动 `LogTrack.track`
运营活动页	② $tracker	`sndd_hs_h5_campaign_view`、`sndd_hs_sy_page_view`
活动宣传组件	② $tracker	`sndd_hs_h5_info_click`
底部活动按钮组件	② $tracker	`sndd_hs_h5_campaign_click`
弹窗组件	② $tracker	弹窗点击
订阅广场组件	② $tracker	订阅广场
订阅包组件	② $tracker	订阅包
首页活动页	A + $timeTrack	`homeActivityMounted`、`homeActivityPageDataLoad` 性能

运营活动大量用 ② $tracker，事件名带 h5_campaign / h5_info 前缀。

用户增长模块

页面	写法	点位
签到活动页	A + ② $tracker	`sndd_hs_click` 签到点击
签到视频列表组件	② $tracker	`sndd_hs_click`、`sndd_hs_show`
签到成功组件	② $tracker	`sndd_hs_show` 签到成功
裂变页	A	裂变页
兑换课程页	A	12 处 click
领礼物页	A	领礼物
券成功页	A	券成功
好友助力页	A	好友助力
勋章分享页	A	勋章分享
邀请吃饭页	A	4 处
邀请有礼页（含分享/任务栏组件）	A	邀请有礼
新签到任务页	A	新签到任务

训练营 / 实体勋章模块

页面	写法	点位
训练营消息群页	A	3 处
训练营新群提示页	A	2 处
训练营群提示页	A	1 处
训练营简化结果页	A + classKey	`camp_config` 远程配置
训练营简化阅读报告页	A + classKey	`camp_config`
训练营短信二维码页	A	3 处
实体勋章页系列（首页/详情/成功/好友/营地）	A + ② $tracker	勋章页系列

classKey: 'camp_config' 是远程配置开关，控制是否开全埋点 / 热力图圈选（详见三大埋点系统 ②）。其它 classKey：h5_exhibition_config、LISTENING_CARD、mall、h5_review。

其它组件

组件	写法	点位
注册组件	A + D v-log	注册流程
验证码输入组件	A + D v-log	`获取验证码`、`立即领取`
留言项组件	D v-log	`点赞`、`取消点赞`
留言组件	D v-log	`写留言`
答题组件（含弹窗）	D v-log	答题
抢音频组件	D v-log	抢音频
标签页组件	D v-log	`ev__course_detail_view`
领礼物按钮组件	D v-log	领礼物按钮
课程按钮组件	D v-log	`ev__course_detail_play`
每日问答页	A	12 处（每日问答）
免费券页	A	免费券
AI 挑战页（含图片组件）	② $tracker	AI 挑战
AI 工具页（含课程列表等）	② $tracker + A	AI 工具页
新报告页	② $tracker	新报告
自动召回课程页	② $tracker	自动召回课程
对话 bot 混入	② $tracker	对话 bot
会员卡逻辑	② $tracker	会员卡 `sndd_hs_${event}`

已有埋点文档清单

接手前，先读这两份既有规格文档（项目维护者写的，比本系列更细）：

文档	内容
项目埋点规格文档	少年闻天下 + 知识卡列表 / 详情页全量埋点字段表
报告页埋点规格文档	报告页时长 / 模块曝光 / 离开时机 / 新老口径差异 / 注意点

下一篇 → 字段口径与 key1 规约

埋点的七种写法

Sat, 22 Aug 2026 12:00:00 +0000

埋点的七种写法

目标：项目里"埋点代码"有七种不同写法。读完这篇你能认出每一种，知道它解决什么问题、照着抄就行。

先记一句话：七种写法只是"怎么调"的不同，背后最终都落到 ① LogTrack 或 ② $tracker 上（见三大埋点系统）。

flowchart TB
    ROOT["业务页面要埋点"] --> P1["A 直接调 LogTrack.track"]
    ROOT --> P2["B 组件内封一层 this.track"]
    ROOT --> P3["C 双系统并行 commLog"]
    ROOT --> P4["D v-log 指令声明式"]
    ROOT --> P5["E EventComponent 配置驱动"]
    ROOT --> P6["F autoTrack 路由自动"]
    ROOT --> P7["G 停留时长心跳"]
    P1 --> S1["LogTrack"]
    P2 --> S1
    P3 --> S1
    P3 --> S2["$tracker"]
    P4 --> S1
    P5 --> S1
    P6 --> S1
    P7 --> S1
    P7 --> S2
    style S1 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style S2 fill:#6b3a2d,color:#fff,stroke:#d9774a
    style ROOT fill:#1e2a3a,color:#fff,stroke:#4a90d9

A · 直接调 `LogTrack.track`

最常见，90% 的页面就用这一种。

import { LogTrack } from '@/utils';

// 点击返回
LogTrack.track({
  page_name: '少年闻天下', page_type: 2, page_title: '少年闻天下',
  url: window.location.href,
  module_name: '导航栏', item_name: '返回按钮', btn_name: '返回',
  key1: JSON.stringify({ user_status: 'member' })
}, 'click');

特征：每次埋点手写完整字段，调 LogTrack.track(obj, eventType)。

代表文件：少年闻天下订阅页（一个文件 23 处）、兑换课程页（12 处）、每日问答页（12 处）。

适用：埋点不多的页面，直接写最清楚。

B · 组件内封一层 `this.track`

问题：一个页面有十几个埋点，每次都写 page_name/page_type/page_title/url 太啰嗦，改一处要改十几处。解法：在组件里封一个 track 方法，把公共字段固定下来，只传变化的部分。

知识卡页面组件：

methods: {
  // 通用埋点：公共字段写死，扩展数据合并进 key1
  track(extra = {}, eventType = 'click') {
    LogTrack.track({
      page_name: '知识卡',
      page_type: 2,
      page_title: '知识卡',
      url: window.location.href,
      main_item_id: '',
      key1: JSON.stringify({
        user_status: this.userStatus || 'normal',
        ...extra.key1Data        // 变化的细节塞这
      }),
      ...extra.other              // module_name/item_name/btn_name 塞这
    }, eventType);
  },

  goToBack() {
    this.track({
      other: { module_name: '导航栏', item_name: '返回按钮', btn_name: '返回' }
    });
  }
}

特征：this.track({ other: {...}, key1Data: {...} }, 'click')，把字段拆成"固定的"和"变化的"两层。

适用：单页面埋点 ≥ 5 处，字段重复多。知识卡列表页、知识卡详情页都用这种。

C · 双系统并行 `commLog`

问题：同一个行为，业务方要求同时进神策/自研（老口径）和火山（新口径）两套后台。解法：封一个方法，里面同时调 LogTrack.track 和 $tracker。

阅读信件报告页：

commLog(event, options) {
  var config = options || {};
  // ① 发火山（新口径，事件名 sndd_hs_xxx）
  this.$tracker('sndd_hs_' + event, this.getTrackerBaseData(config.trackerData));
  // ② 发神策+自研（老口径，事件类型 page/show/click）
  LogTrack.track(Object.assign({}, this.getLogTrackBaseData(config.logData), {
    key1: JSON.stringify({ /* ... */ })
  }), event);
}

特征：一个方法里两行上报，$tracker + LogTrack.track。

注意：两套口径字段名可能不同（详见字段口径），比如时长在 $tracker 里叫 duration_ms，在 LogTrack 里叫 duration。

代表文件：阅读信件报告页、阅读诊断报告页、阶段测评报告页。这三个是本项目埋点最复杂的页面。

D · `v-log` 指令声明式埋点

问题：按钮太多，每个 @click 里写 LogTrack.track 太烦，还容易和业务逻辑混在一起。解法：用 v-log 指令，写在模板上，点一下自动埋点。

1
2

<!-- 点这个按钮自动上报 click -->
<button v-fastclick="sendCode" v-log:click="{ ...log, name: '获取验证码' }">获取验证码</button>

带 ev__ 修饰符可指定事件名：

`1`	`<div v-log:click.ev__course_detail_play="evLogTrack"></div>`

它怎么工作的

v-log 由基础组件库的 vueExtends/log.js 注册。原理：

flowchart LR
    A["v-log:click={...} 写在模板"] --> B["指令把数据存到 dom.dataset.igc_log"]
    B --> C["document.body 监听 click 冒泡"]
    C --> D["点击时找到带 igc_log 的元素"]
    D --> E["内部调 LogTrack.track()"]
    style E fill:#2d4a6b,color:#fff,stroke:#4a90d9

即：v-log 最终也是调 LogTrack，只是把埋点从 JS 搬到了模板上。

代表文件：验证码输入组件、留言项组件、课程按钮组件、音频组件、课程详情页、注册组件、领礼物按钮组件。

适用：纯点击埋点、不想污染业务方法。注意它依赖 v-fastclick，且 <a>/<input>/<button> 标签会被自动识别。

E · EventComponent 配置驱动埋点

问题：运营活动页的组件是后台配置出来的（按钮文案、跳转、事件都由接口返回），写死埋点不现实。解法：用一个通用 EventComponent，根据配置里的 eventType 自动埋点。

活动页事件组件：

trackEvent(eventType) {
  let trackObj = {
    page_name: '专题详情页',
    page_type: 2,
    page_title: this.$parent.activityName,
    item_index: this.$parent.index,
    main_item_type: '活动'
  };
  if (this.componentType === 'button') {
    trackObj.btn_name = this.$parent.btnTxt;
  }
  LogTrack.track(trackObj);   // ← 配置驱动，自动上报
}

特征：埋点字段从 this.$parent（父组件 = 后台配置）取，不写死。

适用：运营活动体系，组件由配置渲染的场景。

F · `autoTrack` 路由自动曝光

问题：每个页面进都手动写一次 page 曝光太容易漏。解法：App 启动时一次性把所有路由注册进自动曝光。

App 根组件：

created() {
  let routes = this.$router.options.routes;
  LogTrack.track({}, 'autoTrack', true, routes);   // ← 全路由自动 page 曝光
  this.$timeTrack('appCreated');
}

特征：LogTrack.track({}, 'autoTrack', true, routes)，第 3、4 个参数是 autoTrack 专用。

背后：神策全埋点，事件 sndd_sensor_autoTrack，切路由自动发页面访问日志，还带 refer_page_name（来源页）链路。

注意：只在 App 根组件调一次，业务页面不要重复调。

G · 停留时长心跳

问题：想知道用户在页面待了多久，但用户可能切后台、可能直接关页面，单一时机抓不准。解法：定时心跳 + 可见性监听 + 离开兜底。

阅读信件报告页是参考实现，核心三个方法：

flowchart TB
    M["mounted → initStayTrack()"] --> H["启动 3 秒心跳定时器"]
    H --> F["flushStayTrack() 每 3 秒上报一次 duration 并重置"]
    V["visibilitychange"] --> Hid{"页面隐藏?"}
    Hid -- 是 --> P["暂停计时 + 立即上报一轮"]
    Hid -- 否 --> R["恢复计时 + 重启心跳"]
    D["beforeDestroy"] --> F2["最后一次 flushStayTrack 上报"]
    style F fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style P fill:#5a3a3a,color:#fff,stroke:#d9534f
    style F2 fill:#3a5a3a,color:#fff,stroke:#5cb85c

关键代码骨架：

data() {
  return {
    pageStayDuration: 0,          // 累计停留毫秒
    pageVisibleStartTime: 0,      // 本轮可见开始时间
    stayTrackHeartbeatTimer: null // 心跳定时器
  };
},
mounted() { /* ... */ this.$nextTick(() => this.initStayTrack()); },
beforeDestroy() { this.flushStayTrack(); /* 最后一次上报 */ },

methods: {
  initStayTrack() {
    this.restartStayTrack();
    document.addEventListener('visibilitychange', this.handleTrackVisibilityChange);
  },
  startStayTrackHeartbeat() {
    this.stayTrackHeartbeatTimer = setTimeout(() => {
      this.flushStayTrack({ resetAfterFlush: true, continueHeartbeat: true });
    }, 3000);                     // ← 每 3 秒
  },
  flushStayTrack(options) {
    this.pausePageDuration();     // 把当前可见段累加进 pageStayDuration
    if (this.pageStayDuration > 0) {
      // 双系统上报时长
      this.$tracker('sndd_hs_page', { /* ..., duration_ms */ });
      LogTrack.track({ /* ..., key1: {duration} */ }, 'page');
    }
    if (options.resetAfterFlush) { this.resetStayTrackState(); }
    if (options.continueHeartbeat) { this.startStayTrackHeartbeat(); }
  },
  handleTrackVisibilityChange() {
    if (document.hidden) { this.stopStayTrackHeartbeat(); this.flushStayTrack({resetAfterFlush:true}); }
    else { this.resumePageDuration(); this.startStayTrackHeartbeat(); }
  }
}

特征：pageStayDuration + pageVisibleStartTime 两个变量管计时，visibilitychange 管切后台，beforeDestroy 兜底。

代表文件：阅读信件报告页、阅读诊断报告页、阶段测评报告页。后两个还多了模块曝光时长（每个模块进视口开始计时、离开累加）。

适用：需要统计"用户看了多久"的报告页 / 内容页。

速查：我该用哪种？

flowchart TD
    Q["要埋点"] --> Q1{"纯点击按钮?"}
    Q1 -- 是 --> D["D · v-log 指令"]
    Q1 -- 否 --> Q2{"运营活动配置页?"}
    Q2 -- 是 --> E["E · EventComponent"]
    Q2 -- 否 --> Q3{"要统计停留时长?"}
    Q3 -- 是 --> G["G · 心跳"]
    Q3 -- 否 --> Q4{"需求点名要 sndd_hs_xxx?"}
    Q4 -- 是 --> Q5{"同时要老口径?"}
    Q5 -- 是 --> C["C · commLog 双发"]
    Q5 -- 否 --> T2["② $tracker"]
    Q4 -- 否 --> Q6{"页面埋点 ≥5 处?"}
    Q6 -- 是 --> B["B · this.track 封装"]
    Q6 -- 否 --> A["A · 直接 LogTrack.track"]
    style A fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style B fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style D fill:#2d4a6b,color:#fff,stroke:#4a90d9

下一篇 → 埋点点位地图

三大埋点系统详解

Sat, 22 Aug 2026 11:00:00 +0000

三大埋点系统详解

目标：搞清每套系统的来源、初始化位置、调用 API、在什么环境生效、什么时候该用。

全景图

flowchart LR
    subgraph 初始化["初始化位置"]
        C1["公共导入模块<br/>LogTrack.config().init()<br/>$timeTrack = logTimeTrack"]
        C2["入口 main.js<br/>logTrackFactory() → $tracker"]
    end
    subgraph SDK["三套系统"]
        S1["① LogTrack<br/>基础组件库"]
        S2["② log-track 实例<br/>log-track-sdk → $tracker"]
        S3["③ logTimeTrack<br/>基础组件库 → $timeTrack"]
    end
    C1 --> S1
    C1 --> S3
    C2 --> S2
    S1 --> R1["神策 Sensors + 自研日志"]
    S2 --> R2["火山引擎 Rangers DataFinder"]
    S3 --> R3["性能计时"]

    style S1 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style S2 fill:#6b3a2d,color:#fff,stroke:#d9774a
    style S3 fill:#5a4a3a,color:#fff,stroke:#c9a04a

LogTrack —— 主埋点系统

来源

来自基础组件库，在工具模块里 re-export，业务页面 import { LogTrack } from '@/utils'。

初始化

公共导入模块：

import { Log, httpRequest, logTimeTrack, LogTrack } from './utils';

if (process.env.VUE_APP_ENVIRONMENT !== 'PRODUCTION') {
  // 非生产：开 debug、同时发自研日志 + 神策日志
  LogTrack.config({ debug: debugLog, customLog: true, sensorsLog: true }).init();
} else {
  LogTrack.init();   // 生产
}

config 三个开关：

参数	含义	默认
`debug`	神策 debug 日志，控制台打印	false
`customLog`	是否发自研日志（`window._la` → `logserver.example.com`）	true
`sensorsLog`	是否发神策 Sensors 日志	true

即：一条 LogTrack.track() 默认会同时发到神策和自研日志两个后台。

调用 API

`1`	`LogTrack.track(trackObj, eventType)`

trackObj：参数对象（page_name、module_name、key1 等，详见字段口径）
eventType：事件类型，四选一

eventType	含义	何时用
`'page'`	页面曝光 / 页面时长	进页面、停留心跳
`'show'`	元素 / 列表展示	列表加载完、弹窗打开
`'click'`	点击交互	用户点按钮、点列表项
`'autoTrack'`	路由自动曝光	仅 App 根组件自动调用，业务别用

调用样例

知识卡页面组件：

import { LogTrack } from '@/utils';
// ...
LogTrack.track({
  page_name: '知识卡',
  page_type: 2,
  page_title: '知识卡',
  url: window.location.href,
  module_name: '导航栏',
  item_name: '返回按钮',
  btn_name: '返回',
  key1: JSON.stringify({ user_status: 'normal' })
}, 'click');

什么时候用

绝大多数业务埋点都用它：页面曝光、列表曝光、按钮点击、弹窗展示、停留时长。

$tracker —— 火山引擎 Rangers（App 内专用）

来源

来自 log-track-sdk，在入口 main.js 里用工厂函数创建实例并挂到 Vue 原型：

import logTrackFactory from 'log-track-sdk';

const logTrackInstance = logTrackFactory(
  process.env.VUE_APP_ENVIRONMENT == 'PRODUCTION' ? 'prod' : 'qa',
  {
    initConfig: { enable_native: false },
    enableOutAPP: false,                                   // ← 关键：浏览器 H5 不跑
    requestAutoTrackParams: { classKey: 'web_auto_track', itemKey: 'project_H5' }
  }
);
logTrackInstance.init();

Vue.prototype.$tracker = (eventName, params) => {
  logTrackInstance.logTrack(eventName, params);
};

它背后到底是谁

读 log-track-sdk 源码，它的 SDK 脚本是：

`1`	`https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.1.6.js`

即火山引擎 Rangers / DataFinder SDK，上报地址 https://gator.volces.com，生产 / 测试各一套 appId。

⚠️ 生效环境（重要）

源码里 init() 只在 平台 === APP || enableOutAPP 时才加载 SDK。本项目 enableOutAPP: false，所以：

flowchart LR
    A["调用 this.$tracker()"] --> B{"在 App 内?"}
    B -- 是 --> C["正常上报火山"]
    B -- 否/纯浏览器 --> D["静默 no-op<br/>什么都不发"]
    style C fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style D fill:#5a3a3a,color:#fff,stroke:#d9534f

纯浏览器里调 $tracker 不会报错，但也不会发任何数据。本地调试时别指望在浏览器 Network 里看到它的请求。

调用 API

`1`	`this.$tracker(eventName, params)`

eventName：自定义事件名，统一加 sndd_hs_ 前缀
params：参数对象

常见事件名（来自真实代码）

事件名	含义
`sndd_hs_page`	页面曝光 / 时长
`sndd_hs_show`	元素展示
`sndd_hs_click`	点击
`sndd_hs_knowledge_publishing_course_play`	音频播放时长
`sndd_hs_h5_campaign_view`	活动页曝光
`sndd_hs_h5_info_click`	活动信息点击

什么时候用

业务方明确要求事件进火山 / DataFinder 后台时
需要和 App 原生埋点对齐口径的自定义事件
音频 / 视频播放时长这类特殊采集

日常页面埋点不要随手用 $tracker，优先用 ① LogTrack。只有需求文档点名要 sndd_hs_xxx 事件时才用。

$timeTrack —— 性能计时点

来源

logTimeTrack 来自基础组件库，在公共导入模块挂到原型：

`1`	`Vue.prototype.$timeTrack = logTimeTrack;`

调用 API

`1`	`this.$timeTrack(label)`

传一个标签名，记录"从启动到现在过了多久"。

调用样例

App 根组件：

created() {
  this.$timeTrack('appCreated');   // Vue 创建时刻
  // ...
}
mounted() {
  this.$timeTrack('appMounted');   // 挂载时刻
}

首页活动页：

1
2

this.$timeTrack('homeActivityMounted');          // 首页挂载
this.$timeTrack('homeActivityPageDataLoad');     // 首页数据加载完

什么时候用

只用来测性能耗时（启动、首屏、数据加载），跟用户行为无关。业务埋点不要用这个。

三套对比一表

	① LogTrack	② $tracker	③ $timeTrack
来源	基础组件库	log-track-sdk	基础组件库
后台	神策 + 自研日志	火山 Rangers	性能后台
生效环境	全环境	仅 App 内	全环境
调用	`LogTrack.track(obj, type)`	`this.$tracker(name, params)`	`this.$timeTrack(label)`
事件类型	page/show/click/autoTrack	自定义 `sndd_hs_*`	计时标签
用途	业务埋点（主力）	自定义事件 / 播放时长	性能监控
占比	~90%	~9%	~1%

下一篇 → 埋点的七种写法

埋点入门：先搞懂埋点是什么

Sat, 22 Aug 2026 10:00:00 +0000

埋点入门：先搞懂"埋点"是什么

目标：读完这篇，你能用自己的话讲清楚"埋点在干嘛"，并知道一套典型前端项目用了哪几套埋点系统。

用一句话理解埋点

埋点 = 在代码里"埋"下记号，把用户做过的事，变成一条条数据，发给后台统计。

打个比方：你开了一家超市，想知道"顾客进门了吗"“拿了哪瓶水"“走到收银台了吗”。你就在门口、货架、收银台各安排一个保安，每发生一件事就记一笔。代码里的"保安"就是埋点代码。

埋点的本质：事件 + 参数

每一条埋点数据，本质就两部分：

flowchart LR
    A["事件 event<br/>发生了什么事"] --- B["参数 params<br/>这件事的细节"]
    style A fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style B fill:#3a5a3a,color:#fff,stroke:#5cb85c

举个例子（真实写法）：

事件：click               ← 用户点了"立即订阅"按钮
参数：
  page_name   = 少年闻天下   ← 在哪个页面
  module_name = 底部购买栏   ← 页面哪个模块
  btn_name    = 立即订阅     ← 具体哪个按钮
  key1        = {"user_status":"member","price":99}  ← 其它细节，打包成 JSON

后台拿到这条数据，就能回答：“有多少人点了立即订阅？会员和非会员各点多少？”

什么时候需要埋点

场景	例子	事件类型
用户打开一个页面	进了"少年闻天下"页	`page` 页面曝光
页面上某个东西展示出来了	课程列表加载出来了	`show` 元素展示
用户点了一下	点了返回、点了课程项	`click` 点击
用户停在这个页面多久	看了 30 秒新闻	`page` + duration 时长
页面性能	App 启动到可交互花多久	计时点

埋点的几个重要性质

埋点不是随便写一行上报就完事。它有几个性质，决定了"埋得好不好”。新手先记住这六条：

flowchart TB
    P1["1 不阻断业务<br/>埋点挂了，用户操作照常"]
    P2["2 离开页要保住<br/>关页面/切后台时数据别丢"]
    P3["3 口径一致<br/>字段名、单位、事件类型全局统一"]
    P4["4 环境开关<br/>不同环境行为不同"]
    P5["5 可追溯<br/>带来源页链路，能还原路径"]
    P6["6 不重不漏<br/>该报的报，别重复报"]

    style P1 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style P2 fill:#3a5a3a,color:#fff,stroke:#5cb85c
    style P3 fill:#5a4a6b,color:#fff,stroke:#9a7acc
    style P4 fill:#6b3a2d,color:#fff,stroke:#d9774a
    style P5 fill:#2d5a4a,color:#fff,stroke:#4ab89a
    style P6 fill:#5a3a3a,color:#fff,stroke:#d9534f

不阻断业务

埋点是"附加动作"，永远排在业务动作之前调用，且不能让它的异常影响用户。

goToBack() {
  this.track({ ... });          // 先埋点
  this.$router.back();          // 再做业务；埋点报错不该影响返回
}

离开页要保住

用户关页面、切后台的瞬间，请求可能还没发出去就断了。所以停留时长类埋点要用心跳定时上报 + visibilitychange 兜底，而不是只等离开那一下才报。（详见写法 G 心跳）

口径一致

同一个概念，全项目字段名、单位必须统一。比如停留时长：LogTrack 里叫 duration、$tracker 里叫 duration_ms，单位都是毫秒——填反或单位错，后台就对不上。（详见字段口径）

环境开关

埋点在不同环境表现不同：生产关 debug、测试开 debug；火山 $tracker 仅 App 内生效、纯浏览器静默不报。改环境要记得核对开关。

可追溯

一条埋点最好能回答"用户从哪来"。autoTrack 自动带 refer_page_name（来源页），能还原用户的浏览路径，不只是孤立的事件。

不重不漏

该报的场景一个不能少（进页、展示、点击、时长），不该重复的别多报。比如 hidden 和 pagehide 都监听时，同一次离开可能报两遍——这是已知风险，要有去重意识。

这六条会在后续每篇里反复出现，带着它们读代码就能看出"为什么这么写"。

一套典型项目用了哪几套埋点系统

这是最关键的一张图。一个 App 内的 H5 项目常常同时跑着三套独立的埋点系统，新手最容易在这里绕晕：

flowchart TB
    subgraph 项目["H5 项目"]
        T1["① LogTrack<br/>神策 + 自研日志<br/>主埋点系统"]
        T2["② $tracker<br/>火山引擎 Rangers<br/>App 内自定义事件"]
        T3["③ $timeTrack<br/>性能计时点"]
    end
    T1 --> B1["神策 Sensors"]
    T1 --> B2["自研日志 logserver"]
    T2 --> B3["火山 DataFinder<br/>gator.volces.com"]
    T3 --> B4["性能监控后台"]

    style T1 fill:#2d4a6b,color:#fff,stroke:#4a90d9
    style T2 fill:#6b3a2d,color:#fff,stroke:#d9774a
    style T3 fill:#5a4a6b,color:#fff,stroke:#9a7acc
    style 项目 fill:#1e2a3a,color:#fff,stroke:#4a90d9

系统	调用样子	发给谁	一句话定位
① LogTrack	`LogTrack.track({...}, 'click')`	神策 + 自研日志	主系统，绝大多数埋点用它
② $tracker	`this.$tracker('sndd_hs_xxx', {...})`	火山引擎 Rangers	仅 App 内生效，自定义事件名
③ $timeTrack	`this.$timeTrack('appCreated')`	性能后台	测启动 / 加载耗时，不是业务埋点

新手记住：90% 的业务埋点用的是 ① LogTrack。② ③ 是特殊场景才用。下一篇详细讲这三套。

埋点代码长什么样（先看个直观例子）

知识卡页面组件里点"返回按钮"的埋点：

goToBack() {
  this.track({                              // 调埋点
    other: { module_name: '导航栏', item_name: '返回按钮', btn_name: '返回' }
  });
  if (env.isApp) {
    JS2Native({ name: 'closeWindow' });     // 真正的业务动作：关 webview
  } else {
    this.$router.back();
  }
}

注意一个新手最容易踩的坑：埋点代码和业务动作是分开的两步。先埋点、再做业务，互不干扰。埋点出错不该影响用户操作。

配套 Demo：亲手玩一遍

光看代码不够直观，我做了个纯本地的 Demo 把这套机制跑给你看——不接任何真实 SDK、不用装依赖，打开就能玩。

👉 打开 Demo

Demo 长这样：左边是一个迷你业务页（列表 / 详情），右边是「埋点事件流」面板，你每做一个动作，面板里就实时冒出对应的上报记录，和后端真正收到的数据一模一样。

怎么玩：

打开页面，右侧已经有 appCreated、autoTrack、列表 show 三条——对应进页自动曝光。
点列表里任意课程项 → 看 click 事件，自动跳进详情页。
在列表页停留 3 秒 → 心跳触发，多一条带 duration 的 page（这就是写法 G）。
点底部「双发演示」按钮 → 同一次点击同时冒出火山和神策+自研两条（写法 C 双系统并行）。
顶部勾选「App 内」→ 火山从「静默」变成真上报；不勾就是纯浏览器静默 no-op。
关掉「神策」或「自研日志」开关 → 对应后端的事件流立刻消失，直观看到环境开关的作用。

把 Demo 和上面讲的六条性质对着看：不阻断业务、离开页保住、环境开关、不重不漏，都能在面板里直接观察到。

下一篇 → 三大埋点系统详解

前端工程化-埋点 on acye's blog

生产环境推荐实践

生产环境推荐实践

教学模拟 vs 生产，差在哪

生产为什么要接真实 SDK（好处）

生产数据流（前端 → 后端 → 看板）

前端研发职责

SDK 接入与初始化

公共字段与开关统一管理

停留时长与离开页兜底

不阻断业务

密钥与脱敏（开源/公开仓库时）

灰度与采样

自测

后端研发职责

接收网关

字段清洗与补全

新老口径映射

去重与幂等

监控与告警

数据落库与查询

前后端协作口径

生产自检清单

字段口径与 key1 规约

字段口径与 key1 规约

LogTrack 标准字段表

哪些字段属于哪类

key1 规约（最重要）

规则

为什么这么做

正确写法

错误写法（别这样）

常见 key1 内部字段

事件类型怎么选

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

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

page_name / page_type 约定（已知）

停留时长单位

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

埋点点位地图

埋点点位地图

模块全景

全局入口

报告页模块（埋点最复杂）

少年闻天下 / 知识卡模块

课程 / 内容消费模块

运营活动模块

用户增长模块

训练营 / 实体勋章模块

其它组件

已有埋点文档清单

埋点的七种写法

埋点的七种写法

A · 直接调 LogTrack.track

B · 组件内封一层 this.track

C · 双系统并行 commLog

D · v-log 指令声明式埋点

它怎么工作的

E · EventComponent 配置驱动埋点

F · autoTrack 路由自动曝光

G · 停留时长心跳

速查：我该用哪种？

三大埋点系统详解

三大埋点系统详解

全景图

LogTrack —— 主埋点系统

来源

初始化

调用 API

调用样例

什么时候用

$tracker —— 火山引擎 Rangers（App 内专用）

来源

它背后到底是谁

⚠️ 生效环境（重要）

调用 API

常见事件名（来自真实代码）

什么时候用

$timeTrack —— 性能计时点

来源

A · 直接调 `LogTrack.track`

B · 组件内封一层 `this.track`

C · 双系统并行 `commLog`

D · `v-log` 指令声明式埋点

F · `autoTrack` 路由自动曝光