@rk911/tracker-sdk 1.6.4 → 1.6.5

package/README.md

@@ -0,0 +1,204 @@
+# @rk911/tracker-sdk
+
+人康多端埋点 SDK — 自动化采集 + 手动埋点兼容。
+
+支持 H5、微信小程序、APP（uni-app Vue 2）三端统一的前端数据采集方案，提供自动采集（页面浏览、点击、页面停留、元素曝光、JS 错误、API 监控、滚动深度、应用生命周期、性能指标）和手动埋点（`$dadian` / `$track`）能力。
+
+## 安装
+
+```bash
+npm install @rk911/tracker-sdk
+```
+
+或直接将 `tracker-sdk/` 文件夹复制到项目根目录。
+
+## 快速开始
+
+### Vue 插件方式（推荐）
+
+```javascript
+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 上下文
+
+```javascript
+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-*` 属性来丰富点击事件数据：
+
+```html
+<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 对象 |
+
+## 动态参数解析器
+
+```javascript
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk911/tracker-sdk",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "人康多端埋点 SDK — 自动化采集 + 手动埋点兼容",
   "main": "index.js",
   "module": "index.js",
@@ -11,7 +11,12 @@
     "plugins/",
     "customize/"
   ],
-  "keywords": ["tracker", "analytics", "uni-app", "埋点"],
+  "keywords": [
+    "tracker",
+    "analytics",
+    "uni-app",
+    "埋点"
+  ],
   "author": "rk-team",
   "license": "MIT",
   "publishConfig": {