npm package: @liun1an/tracking-sdk
Description: UTM 感知的前端行为追踪 SDK
Author: Your Organization
Latest version: 1.2.4

# 前端行为追踪 SDK

**中文版** | [English](./README.md)

# SDK 概览

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

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

## 安装与初始化

### 1. 安装前端SDK
```bash
npm install @track-system/sdk
```

### 2. 初始化追踪
```typescript
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
```typescript
// 暂停单个自动追踪
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 }
```

#### 典型使用场景
```typescript
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