@rk911/tracker-sdk 1.6.4 → 1.6.7

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/core/compat.js

@@ -178,6 +178,9 @@ export function createPageStayMixin(tracker) {
       } catch (e) {}
       if (!route) return
       this._pageStayRoute = route.charAt(0) === '/' ? route : '/' + route
+      this._pageStayReferrer = tracker.getReferrer() || null
+      // 解决 onLoad 内打点 pageRoute 错位问题：进入新页面 onLoad 时立即同步更新 SDK 路由状态
+      tracker.updatePageRoute(this._pageStayRoute)
       this._pageStayTitle = ''
       try {
         if (typeof document !== 'undefined' && document.title) {
@@ -332,6 +335,7 @@ export function createPageStayMixin(tracker) {
 
         tracker.track('page_stay', {
           pageRoute: this._pageStayRoute,
+          referrer: this._pageStayReferrer || tracker.getReferrer() || null,
           pageTitle: this._pageStayTitle || null,
           duration: duration,
           frontUrl: stayFrontUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk911/tracker-sdk",
-  "version": "1.6.4",
+  "version": "1.6.7",
   "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": {

package/plugins/api-watch.js

@@ -188,37 +188,16 @@ export class ApiWatchPlugin {
     return str
   }
 
+  // header 直接透传（不再做混淆/截断）——原 _encryptValue 会把 token 截断成前16字节
+  // 导致后台无法还原（[解码失败]），已移除。敏感 header 现以明文上报。
   _filterHeaders(headers) {
     if (!headers || typeof headers !== 'object') return null
-    var filtered = {}
-    var sensitiveKeys = ['authorization', 'token', 'rsb-token', 'cookie', 'set-cookie']
+    var copy = {}
     for (var key in headers) {
       if (!headers.hasOwnProperty(key)) continue
-      if (sensitiveKeys.indexOf(key.toLowerCase()) >= 0) {
-        filtered[key] = this._encryptValue(headers[key])
-      } else {
-        filtered[key] = headers[key]
-      }
-    }
-    return filtered
-  }
-
-  _encryptValue(value) {
-    if (!value) return ''
-    try {
-      var encoded = encodeURIComponent(value)
-      var result = ''
-      for (var i = 0; i < encoded.length; i++) {
-        result += String.fromCharCode(encoded.charCodeAt(i) ^ 0x5A)
-      }
-      var full = btoa(result)
-      if (full.length > 16) {
-        return 'ENC:' + full.substring(0, 16) + '...'
-      }
-      return 'ENC:' + full
-    } catch (e) {
-      return ''
+      copy[key] = headers[key]
     }
+    return copy
   }
 
   destroy() {

package/plugins/click.js

@@ -261,6 +261,19 @@ export class ClickPlugin {
     var text = (container.innerText || container.textContent || '').trim()
     // 排除空文本
     if (!text) return ''
+    // 若包含换行符（弹窗/引导层容器），提取最符合按钮特性的短行
+    if (text.indexOf('\n') > -1) {
+      var lines = text.split('\n').map(function (l) { return l.trim() }).filter(Boolean)
+      if (lines.length > 0) {
+        for (var i = lines.length - 1; i >= 0; i--) {
+          if (lines[i].length > 0 && lines[i].length <= 12) {
+            text = lines[i]
+            break
+          }
+        }
+        if (text.indexOf('\n') > -1) text = lines[0]
+      }
+    }
     // 排除图标字体单字符（Unicode 私用区）
     if (text.length === 1 && text.charCodeAt(0) > 0xe000) return ''
     // [PROJECT-ADAPT] 设计工具命名过滤

package/plugins/js-error.js

@@ -57,7 +57,8 @@ export class JsErrorPlugin {
       }
     }
 
-    var fingerprint = 'vue|' + message + '|' + componentName + '|' + (info || '')
+    var route = this._getCurrentRoute()
+    var fingerprint = 'vue|' + route + '|' + message + '|' + componentName + '|' + (info || '')
 
     if (this._isDuplicate(fingerprint)) return
     if (!this._shouldReport()) return

package/plugins/page-view.js

@@ -90,6 +90,9 @@ export class PageViewPlugin {
     // 去重：同一个页面不重复上报
     if (currentPage === this._lastPage) return
 
+    // 锁定进页时刻的时间戳（避免被后方的 title 异步重试链延迟 100~500ms）
+    var entryTimestamp = adapter.getTimestamp()
+
     // 防抖：同路由 500ms 内不重复上报（防框架路由重入导致的竞态）
     var now = Date.now()
     if (this._lastFiredRoute === currentPage && now - this._lastFiredTime < 500) return
@@ -144,6 +147,7 @@ export class PageViewPlugin {
         pageRoute: currentPage,
         page: currentPage,
         pageTitle: title,
+        timestamp: entryTimestamp,
       })
     }
     reportWithTitle()