@liun1an/tracking-sdk

v1.2.4

Published

3 months ago

UTM 感知的前端行为追踪 SDK

0High
0Medium
0Low

liun1an

tracking analytics utm behavior sdk

前端行为追踪 SDK

中文版 | English

SDK 概览

UTM 感知、指纹驱动的行为追踪 SDK，开箱即上报基础事件，并提供多个高阶行为 helper：

浏览器指纹自动生成
UTM 参数解析与持久化
多种行为埋点便捷封装（页面曝光、滚动速度、滚动深度、久留/离开、路由跳转、点击等）
多层传输降级（sendBeacon → fetch keepalive → XHR → GIF）
与 /api/v1/track 接口字段一一映射

安装与初始化

1. 安装前端SDK

npm install @track-system/sdk

2. 初始化追踪

import { createTracker } from '@track-system/sdk'

const tracker = createTracker({
  endpoint: 'https://your-domain.com/api/v1/track',
  autoInit: true,
  autoTrackPageView: true,
  autoTrackScrollDepth: true  // 自动监控每个页面的滚动深度
})

// 追踪自定义事件（event_params 仅支持字符串/数字/布尔/Null，复杂对象请先序列化）
tracker.track('button_click', {
  section: 'hero',
  buttonText: '立即开始'
})

常用能力速览

| 功能 | 调用方法 | 说明 | | --- | --- | --- | | 手动埋点 | tracker.track(event, data) | data 仅支持原始值，复杂对象请 JSON.stringify | | 元素曝光 | tracker.trackVisible('#banner', 'banner_view') | 支持 triggerOnce: false、自定义额外数据 | | 滚动速度 | tracker.trackScrollSpeed({ threshold: 200 }) | 超过阈值触发 | | 滚动深度 | tracker.trackScrollDepth({ thresholds: [25, 50, 75, 100] }) | 手动监控滚动深度 | | 页面停留 | tracker.trackPageDuration('page_duration') | 返回 cleanup，可按需取消 | | 路由变化 | tracker.trackRouteChanges({ eventName: 'route_change' }) | 适合 SPA | | 用户久停/唤醒 | tracker.trackInactivity({ timeoutMs: 60000 }) | 超时上报 inactive，再次活动上报 active | | 点击行为 | tracker.trackClicks('[data-track]', { includeText: true }) | 监听元素或选择器 | | 暂停自动追踪 | tracker.pauseAutoTracking('scroll_depth') | 暂停单个/多个/所有自动追踪 | | 恢复自动追踪 | tracker.resumeAutoTracking('scroll_depth') | 恢复单个/多个/所有自动追踪 | | 查询追踪状态 | tracker.getAutoTrackingStatus('page_view') | 查询自动追踪功能启用状态 |

调用最佳实践

1. 初始化顺序与配置

必填项：endpoint 指向后端 /api/v1/track；生产环境建议使用 HTTPS 与域名白名单。
自动初始化：autoInit: true 默认在构造后立即执行 init()，若需等待业务准备，可设为 false 并在合适时机 await tracker.init()。
自动事件：autoTrackPageView 默认为开启，若页面已有自定义上报逻辑可关闭避免重复。
调试模式：debugMode: true 会输出所有上报参数与触发条件检查结果，推荐在联调阶段打开。

2. 统一的自动追踪管理（新架构）

SDK 提供统一的自动追踪管理机制，可以灵活控制所有自动追踪功能的启停状态。

自动追踪功能列表

page_view - 页面浏览自动追踪（每次路径变化时触发）
scroll_depth - 滚动深度自动追踪（页面切换时自动重置）

统一管理 API

// 暂停单个自动追踪
tracker.pauseAutoTracking('scroll_depth')

// 暂停多个自动追踪
tracker.pauseAutoTracking(['page_view', 'scroll_depth'])

// 暂停所有自动追踪
tracker.pauseAutoTracking()

// 恢复单个自动追踪
tracker.resumeAutoTracking('scroll_depth')

// 恢复多个自动追踪
tracker.resumeAutoTracking(['page_view', 'scroll_depth'])

// 恢复所有自动追踪
tracker.resumeAutoTracking()

// 查询单个功能状态
const isEnabled = tracker.getAutoTrackingStatus('scroll_depth')  // boolean

// 查询所有功能状态
const allStatus = tracker.getAutoTrackingStatus()  
// { page_view: true, scroll_depth: false }

典型使用场景

const tracker = createTracker({
  endpoint: 'https://your-domain.com/api/v1/track',
  autoTrackPageView: true,
  autoTrackScrollDepth: {
    thresholds: [10, 25, 50, 75, 90, 100],
    eventName: 'page_scroll_depth',
    throttleMs: 200
  }
})

// 场景1：视频播放时暂停滚动追踪
function onVideoPlay() {
  tracker.pauseAutoTracking('scroll_depth')
}

function onVideoPause() {
  tracker.resumeAutoTracking('scroll_depth')
}

// 场景2：用户进入特定模式时暂停所有追踪
function enterFocusMode() {
  tracker.pauseAutoTracking()  // 暂停所有
}

function exitFocusMode() {
  tracker.resumeAutoTracking()  // 恢复所有
}

// 场景3：根据用户偏好动态控制
if (userPreference.disableTracking) {
  tracker.pauseAutoTracking(['page_view', 'scroll_depth'])
}

架构优势

统一管理 - 所有自动功能使用相同的 API，降低学习成本
灵活控制 - 支持单个、批量、全部三种粒度的控制
状态查询 - 随时查询任意功能的启用状态
自动清理 - 页面切换时自动管理监听器生命周期
扩展性强 - 新增自动功能只需注册到系统中

3. 渠道识别与 UTM 持久化

首次访问带 UTM 的 URL 时，init() 会通过 UTMManager.parseURL() 解析 utm_source、utm_medium、utm_campaign 等并写入 localStorage（失败时降级为 Cookie）。
后续页面即使没有携带 query，track() 依旧会通过 utmManager.getFromStorage() 自动附带首跳渠道，满足"多页会话中保留渠道"诉求。
再次访问若 URL 中存在新的 UTM，SDK 会检测到并覆盖旧值，确保渠道信息始终与最近一次带 UTM 的落地页一致。
可使用 registerParameter('channel', parser) 等方式扩展自定义渠道字段；触发条件可组合 has_utm_source、has_utm_campaign 或业务自定义条件对监控做灰度控制。

3. 事件上报策略

在初始化完成前触发的事件会进入队列，待 init() 结束后自动补发，无需额外等待处理。
autoTrackPageView 开启后，SDK 会在初次加载及每次 history.pushState / replaceState / popstate / hashchange 触发时自动上报 page_view，并在事件中附带 reason 与最新 page_path，无需业务手动补埋点。
data 与 extraData 仅支持原始值或可序列化对象，复杂结构建议先转成字符串。
推荐将页面结构组件与事件名称建立映射，保证同一事件名只表达一种业务行为；extraData 用于传递实验组、用户分群等上下文。
对于表单/按钮等关键路径，习惯性封装成 helper（参照 example.html 中的按钮点击示例）以保持一致的字段命名。

4. 多页面与 SPA 集成

多页面应用（MPA）：在各页面以相同配置调用 createTracker() 即可，UTM 持久化依赖于浏览器存储，天然跨页共享。
单页应用（SPA）：
- 应在应用启动阶段创建单例 tracker，并在路由容器 mount 后调用 trackRouteChanges() 获取导航事件。
- 若内部导航会生成新的 UTM（如通过前端 router 拼接 query），需在导航完成后主动刷新页面或重新创建 tracker 以重新解析最新 UTM。
- 对于从外部渠道重新进入 SPA 的场景（浏览器真正重新加载），SDK 会自动覆盖旧的 UTM 数据，无需额外操作。
- 自动追踪与 SPA 完美配合，每次路由变化时会自动重置需要重置的监听（如 scroll_depth），无需手动管理。

5. 调试与排查流程

使用 debugMode 观察控制台输出：包括初始化流程、触发条件状态、自动追踪启停以及各次事件 payload。
example.html 提供了端到端操场，可模拟注册参数、触发条件、滚动/曝光/点击等场景，推荐在业务联调前完成全流程验证。
若发现事件未上报，优先核对触发条件：setTriggerConditions([]) 可退回"始终监控"模式便于定位问题。
使用 getAutoTrackingStatus() 检查自动追踪功能的状态，确认是否被意外暂停。

6. 上线前检查清单

已确认后端 /api/v1/track 接口返回统一 { success, data/error, meta } 结构，字段名与 SDK 输出一致。
核对浏览器兼容策略：需支持 localStorage、sendBeacon 与 fetch keepalive；在老旧浏览器中会自动降级为 XHR/GIF。
确认已在必要页面加载 SDK，并在业务代码中引用同一 tracker 实例，避免重复生成指纹。
针对 GDPR/隐私合规项目，确保在用户授权后再调用 createTracker() 或延迟 init()。

更多示例见 README 英文版及 example.html。

注意事项

SDK 内部会自动生成浏览器指纹并缓存在内存
UTM 参数解析后存储于 localStorage，并用于触发条件判断
支持 sendBeacon → fetch → XHR → GIF 的逐级降级，保证事件可靠上报
若需要自定义 UTM 参数解析，可调用 tracker.registerParameter
若需控制事件触发条件，可使用 tracker.setTriggerConditions(['has_utm_source'])

升级日志

1.3.0 (架构升级)
- 🎉 新增统一的自动追踪管理机制 - 所有自动追踪功能（page_view、scroll_depth）现在使用统一的管理器
- 新增 pauseAutoTracking(name?) API - 暂停单个/多个/所有自动追踪功能
- 新增 resumeAutoTracking(name?) API - 恢复单个/多个/所有自动追踪功能
- 新增 getAutoTrackingStatus(name?) API - 查询自动追踪功能的启用状态
- 优化页面切换时的生命周期管理 - 自动重置需要重置的监听器（如 scroll_depth）
- 移除旧的 stopScrollDepthTracking() API（请使用 pauseAutoTracking('scroll_depth')）
- 移除 page_leave 自动追踪功能及 autoTrackPageLeave 配置项
- 提升扩展性 - 新增自动追踪功能只需注册到系统中即可
1.2.0
- 新增自动滚动深度监控功能 autoTrackScrollDepth，支持页面切换时自动重置监听
- 支持传入详细配置对象自定义滚动深度阈值、事件名称等
- 优化页面导航时的监听器生命周期管理
1.1.0
- 新增事件队列，初始化前调用 track() 也会等待发送
- 新增滚动深度、路由变化、闲置检测、点击追踪等 helper
- trackScrollSpeed、trackPageDuration、trackVisible 等支持清理函数和自定义事件名
- 自动事件配置支持 autoTrackPageView
- 增强事件数据规整，确保与后端校验一致

License

MIT