@rk911/tracker-sdk

人康多端埋点 SDK — 自动化采集 + 手动埋点兼容。

支持 H5、微信小程序、APP（uni-app Vue 2）三端统一的前端数据采集方案，提供自动采集（页面浏览、点击、页面停留、元素曝光、JS 错误、API 监控、滚动深度、应用生命周期、性能指标）和手动埋点（$dadian / $track）能力。

安装

npm install @rk911/tracker-sdk

或直接将 tracker-sdk/ 文件夹复制到项目根目录。

快速开始

Vue 插件方式（推荐）

import TrackerSDK from '@rk911/tracker-sdk'

Vue.use(TrackerSDK, {
  appId: '1',
  dadianUrl: 'https://state.renruikeji.cn',
  platform: 'web', // 'web' | 'weapp' | 'app'
  pflag: 0,
  tokenKey: 'token',
  plugins: ['page-view', 'click', 'page-stay', 'exposure', 'js-error', 'api-watch', 'app-lifecycle', 'performance', 'scroll-depth'],
  getAuthHeaders: () => ({ Authorization: token, token: token }),
  useUnifiedReport: true,
  debug: false,
})

非 Vue 上下文

import { getTracker } from '@rk911/tracker-sdk'

const tracker = getTracker()
if (tracker) {
  tracker.track('custom', { eventName: 'someEvent', data: 'value' })
}

配置项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | — | 必填，应用 ID | | dadianUrl | string | — | 必填，上报地址 | | platform | string | 'web' | 平台：web / weapp / app | | pflag | number | 0 | 业务平台标识（0-5） | | tokenKey | string | 'token' | 登录 token 的 storage key（小程序用 'tokenV2'） | | plugins | array | [] | 启用的插件列表 | | getAuthHeaders | function | — | 返回请求头的函数 | | useUnifiedReport | boolean | true | true=仅 SDK 上报，false=双通道上报 | | allowAnonymousTrack | boolean | false | 是否允许未登录上报 | | sampling | number | 1 | 采样率（0-1），会话级生效 | | debug | boolean | false | 开启调试日志 | | queue.maxBatchSize | number | 10 | 批量上报大小 | | queue.flushInterval | number | 60000 | 定时上报间隔(ms) | | queue.clickFlushDelay | number | 3000 | 点击事件延迟上报(ms) | | session.timeout | number | 1800000 | 会话超时时间(ms) | | pageStay.minStayDuration | number | 2000 | 最小停留时长(ms) | | pageStay.maxStayDuration | number | 1800000 | 最大停留时长(ms) | | exposure.validExposureTime | number | 1000 | 曝光有效时间(ms) | | exposure.threshold | number | 0.5 | 曝光面积阈值 | | scrollDepth.throttle | number | 1000 | 滚动节流间隔(ms) |

API

Vue 实例方法

| 方法 | 说明 | |------|------| | this.$track(frontUrl, postParam) | 手动埋点（推荐） | | this.$dadian(frontUrl, postParam) | 手动埋点（向后兼容） | | this.$tracker | 获取 Tracker 实例 | | this.$trackerResetSession() | 重置会话（登出时调用） | | this.$registerParam(name, fn) | 注册动态参数解析器 |

Vue 指令

| 指令 | 说明 | |------|------| | v-track-exposure | 元素曝光指令（推荐） | | v-impression | 曝光兼容指令（旧项目） |

Tracker 实例方法

| 方法 | 说明 | |------|------| | tracker.track(eventType, data) | 核心事件上报 | | tracker.setUser(userId) | 设置用户 ID | | tracker.setDeviceId(deviceId) | 设置设备 ID | | tracker.setUserProperties(props) | 设置用户属性 | | tracker.registerParam(name, fn) | 注册动态参数解析器 | | tracker.unregisterParam(name) | 注销动态参数解析器 | | tracker.updatePageRoute(newPage) | 手动更新页面路由 | | tracker.getReferrer() | 获取当前 referrer | | tracker.onReport(fn) | 监听事件入队 | | tracker.destroy() | 销毁实例，释放资源 |

数据属性

在 HTML 元素上添加以下 data-track-* 属性来丰富点击事件数据：

<button
  data-track-id="order_submit"
  data-track-name="提交订单"
  data-track-ext-key="orderId"
  data-track-ext-value="123456"
  data-track-param="orderDetail"
>
  提交
</button>

| 属性 | 说明 | |------|------| | data-track-id | 埋点标识（会将事件类型提升为 custom） | | data-track-name | 人类可读名称 | | data-track-ext-key | 扩展字段 key | | data-track-ext-value | 扩展字段 value | | data-track-ext-int | 扩展整数字段 | | data-track-param | 动态参数解析器名称 | | data-track-post-* | 自动收集到 postParam 对象 |

动态参数解析器

this.$registerParam('goodsDetail', (el) => ({
  extKey: 'goodsId',
  extValue: String(store.state.goods.id),
  extIntValue: store.state.goods.price,
  postParam: { goodsId: store.state.goods.id, skuId: store.state.goods.skuId }
}))

插件列表

| 插件 | 说明 | |------|------| | page-view | 自动追踪页面浏览，路由变化检测 | | click | 自动追踪点击，丰富元素识别策略 | | page-stay | 页面停留时长追踪 | | exposure | 元素曝光（IntersectionObserver + MutationObserver） | | js-error | JS 错误捕获（运行时、Promise、资源加载、Vue 组件错误） | | api-watch | API 请求监控（uni.addInterceptor） | | app-lifecycle | 前后台切换事件 | | performance | Web Vitals（DNS、TTFB、FCP、LCP、DOM Ready、Load） | | scroll-depth | 滚动深度追踪 |

平台支持

| 平台 | 适配器 | 说明 | |------|--------|------| | H5 | WebAdapter | 完整 DOM 访问，支持 hash/history 路由 | | 微信小程序 | WeappAdapter | 无 DOM，内存 sessionStorage，生命周期 mixin | | APP | AppAdapter | 继承 WebAdapter，集成 NativeBridge |

平台自动检测：有 wx 且无 document → 小程序；有 window + document → web；默认 web。

项目结构

tracker-sdk/
├── index.js              # 入口：Vue 插件、createTracker、平台检测
├── core/
│   ├── tracker.js        # Tracker 类：插件管理、事件上报、采样
│   ├── config.js         # 默认配置、深度合并、校验
│   ├── session.js        # 会话管理：ID、设备、过期、序列号
│   ├── queue.js          # 上报队列：批量、定时、离线缓存、sendBeacon
│   └── compat.js         # 兼容层：$dadian、v-impression、page-stay mixin
├── platforms/
│   ├── web.js            # H5 适配器
│   ├── weapp.js          # 微信小程序适配器
│   └── app.js            # APP 适配器（NativeBridge）
├── plugins/
│   ├── page-view.js      # 页面浏览
│   ├── click.js          # 点击
│   ├── page-stay.js      # 页面停留
│   ├── exposure.js       # 元素曝光
│   ├── js-error.js       # JS 错误
│   ├── api-watch.js      # API 监控
│   ├── app-lifecycle.js  # 应用生命周期
│   ├── performance.js    # 性能指标
│   └── scroll-depth.js   # 滚动深度
├── customize/
│   ├── index.js          # 项目规则分发
│   └── modules/
│       ├── common.js     # 公共 uni-app 规则
│       └── store-manager.js  # 店掌项目规则
└── docs/
    ├── SDK_DESIGN.md     # 设计文档
    ├── BACKEND_DESIGN.md # 后端接口设计
    └── ROADMAP.md        # 路线图

License

MIT