@rk911/tracker-sdk 1.6.4

package/plugins/exposure.js

@@ -0,0 +1,376 @@
+/**
+ * 元素曝光插件（增强版）
+ *
+ * 能力：
+ * 1. v-track-exposure 指令 — 走 SDK 自动采集链路
+ * 2. 停留时长验证 — 元素必须完全可见超过 validExposureTime 才算有效曝光
+ * 3. 退出比例判定 — 可见比例低于 exitRatio 时取消计时
+ * 4. MutationObserver — 动态 DOM 元素自动挂载观察
+ * 5. v-impression 兼容 — 在 compat.js 中单独处理，与本插件并存
+ *
+ * 配置（通过 tracker config.exposure 传入）：
+ *   validExposureTime: number  — 有效曝光最小停留时长（ms），默认 1000
+ *   exitRatio: number          — 低于此比例判定为离开视口，默认 0.7
+ *   threshold: number          — 普通模式的可见比例阈值，默认 0.5
+ *   useDuration: boolean       — 是否启用停留时长验证模式，默认 false
+ *   observeDynamicElements: boolean — 是否监控动态 DOM，默认 true
+ */
+export class ExposurePlugin {
+  constructor() {
+    this.name = 'exposure'
+    this.tracker = null
+    this._observers = null
+    this._reported = null
+    this._entryTimers = null
+    this._intersectionObserver = null
+    this._mutationObserver = null
+    this._config = null
+  }
+
+  install(tracker) {
+    this.tracker = tracker
+    var adapter = tracker.getAdapter()
+
+    if (!adapter.supportsIntersectionObserver()) return
+
+    this._observers = new WeakMap()
+    this._reported = new WeakSet()
+    this._entryTimers = new WeakMap()
+
+    // 读取曝光配置
+    var trackerConfig = tracker.getConfig()
+    this._config = {
+      validExposureTime: 1000,
+      exitRatio: 0.7,
+      threshold: 0.5,
+      useDuration: false,
+      observeDynamicElements: true,
+      ...(trackerConfig.exposure || {}),
+    }
+
+    // 在 H5 端自动监控 data-exposure 属性元素
+    if (adapter.supportsDOM()) {
+      this._initAutoExposure()
+    }
+  }
+
+  /**
+   * 自动监控页面上带 data-exposure / data-scroll-exposure 属性的元素
+   */
+  _initAutoExposure() {
+    var self = this
+    var config = this._config
+    var tracker = this.tracker
+    var adapter = tracker.getAdapter()
+
+    // 计算 IntersectionObserver 阈值
+    var thresholds
+    if (config.useDuration) {
+      thresholds = [0, config.exitRatio, 1.0]
+    } else {
+      thresholds = [0, config.threshold]
+    }
+
+    this._intersectionObserver = new IntersectionObserver(
+      function (entries) {
+        entries.forEach(function (entry) {
+          var el = entry.target
+          if (self._reported.has(el)) return
+
+          if (config.useDuration) {
+            self._handleDurationExposure(el, entry)
+          } else {
+            self._handleSimpleExposure(el, entry)
+          }
+        })
+      },
+      { root: null, rootMargin: '0px', threshold: thresholds }
+    )
+
+    // 观察现有元素
+    this._observeExistingElements()
+
+    // MutationObserver 监控动态元素
+    if (config.observeDynamicElements && typeof MutationObserver !== 'undefined') {
+      this._initMutationObserver()
+    }
+  }
+
+  /**
+   * 普通模式：可见比例超过阈值即上报
+   */
+  _handleSimpleExposure(el, entry) {
+    if (
+      entry.isIntersecting &&
+      entry.intersectionRatio >= this._config.threshold
+    ) {
+      this._reportExposure(el, entry.intersectionRatio)
+    }
+  }
+
+  /**
+   * 停留时长验证模式：元素 100% 可见 + 持续 N 毫秒才算有效曝光
+   * 移植自 smart-tracker 的 _handleDurationBasedExposure
+   */
+  _handleDurationExposure(el, entry) {
+    var self = this
+    var config = this._config
+
+    if (entry.intersectionRatio >= 1.0) {
+      // 元素完全进入视口 — 开始计时
+      if (this._entryTimers.has(el)) return
+
+      var timerId = setTimeout(function () {
+        if (self._reported.has(el)) {
+          self._entryTimers.delete(el)
+          return
+        }
+        self._reportExposure(el, 1.0)
+        self._entryTimers.delete(el)
+      }, config.validExposureTime)
+
+      this._entryTimers.set(el, timerId)
+    } else if (entry.intersectionRatio < config.exitRatio) {
+      // 可见比例低于退出阈值 — 取消计时
+      var timerId = this._entryTimers.get(el)
+      if (timerId) {
+        clearTimeout(timerId)
+        this._entryTimers.delete(el)
+      }
+    }
+  }
+
+  /**
+   * 上报曝光事件
+   */
+  _reportExposure(el, visibleRatio) {
+    this._reported.add(el)
+
+    // 尝试 unobserve
+    if (this._intersectionObserver) {
+      this._intersectionObserver.unobserve(el)
+    }
+
+    var adapter = this.tracker.getAdapter()
+    var trackData = {
+      trackId: (el.dataset && el.dataset.trackId) || undefined,
+      trackName:
+        (el.dataset && el.dataset.trackName) ||
+        (el.dataset && el.dataset.exposure) ||
+        undefined,
+      text: (el.innerText || '').trim().substring(0, 50),
+      xpath: adapter.getXPath(el),
+      visibleRatio: visibleRatio,
+    }
+
+    // 如果元素上有自定义数据
+    if (el._trackExposureData) {
+      trackData.customData = el._trackExposureData
+    }
+
+    this.tracker.track('exposure', trackData)
+  }
+
+  /**
+   * 观察页面上已有的 data-exposure 元素
+   */
+  _observeExistingElements() {
+    if (!this._intersectionObserver || typeof document === 'undefined') return
+
+    var elements = document.querySelectorAll(
+      '[data-exposure], [data-scroll-exposure]'
+    )
+    var self = this
+    elements.forEach(function (el) {
+      self._intersectionObserver.observe(el)
+    })
+  }
+
+  /**
+   * MutationObserver：监控动态添加的带曝光属性的元素
+   * 移植自 smart-tracker 的 _observeDOMChanges
+   */
+  _initMutationObserver() {
+    if (typeof document === 'undefined' || !document.body) return
+
+    var self = this
+    this._mutationObserver = new MutationObserver(function (mutations) {
+      mutations.forEach(function (mutation) {
+        mutation.addedNodes.forEach(function (node) {
+          if (node.nodeType !== 1) return // 只处理元素节点
+
+          // 检查节点本身
+          if (
+            node.hasAttribute &&
+            (node.hasAttribute('data-exposure') ||
+              node.hasAttribute('data-scroll-exposure'))
+          ) {
+            if (!self._reported.has(node)) {
+              self._intersectionObserver.observe(node)
+            }
+          }
+
+          // 检查子元素
+          if (node.querySelectorAll) {
+            var children = node.querySelectorAll(
+              '[data-exposure], [data-scroll-exposure]'
+            )
+            children.forEach(function (child) {
+              if (!self._reported.has(child)) {
+                self._intersectionObserver.observe(child)
+              }
+            })
+          }
+        })
+      })
+    })
+
+    this._mutationObserver.observe(document.body, {
+      childList: true,
+      subtree: true,
+    })
+  }
+
+  /**
+   * 返回 v-track-exposure 指令定义（Vue 2 格式）
+   * 用法：v-track-exposure="{ name: '商品卡片', id: goodsId }"
+   */
+  createDirective() {
+    var self = this
+    var observers = this._observers
+    var reported = this._reported
+    var entryTimers = this._entryTimers
+    var tracker = this.tracker
+    var config = this._config
+
+    if (!observers || !reported || !tracker) return null
+
+    function handleIntersection(entries, observer) {
+      entries.forEach(function (entry) {
+        var el = entry.target
+        if (reported.has(el)) return
+
+        if (config && config.useDuration) {
+          // 停留时长验证模式
+          if (entry.intersectionRatio >= 1.0) {
+            if (entryTimers.has(el)) return
+            var timerId = setTimeout(function () {
+              if (reported.has(el)) {
+                entryTimers.delete(el)
+                return
+              }
+              reported.add(el)
+              observer.unobserve(el)
+
+              var data = el._trackExposureData || {}
+              var adapter = tracker.getAdapter()
+              tracker.track('exposure', {
+                trackId:
+                  (el.dataset && el.dataset.trackId) || data.id || undefined,
+                trackName:
+                  (el.dataset && el.dataset.trackName) ||
+                  data.name ||
+                  undefined,
+                text: (el.innerText || '').trim().substring(0, 50),
+                xpath: adapter.getXPath(el),
+                visibleRatio: 1.0,
+                viewDuration: config.validExposureTime,
+                customData: data,
+              })
+              entryTimers.delete(el)
+            }, config.validExposureTime)
+            entryTimers.set(el, timerId)
+          } else if (entry.intersectionRatio < config.exitRatio) {
+            var tid = entryTimers.get(el)
+            if (tid) {
+              clearTimeout(tid)
+              entryTimers.delete(el)
+            }
+          }
+        } else {
+          // 普通模式
+          var threshold = (config && config.threshold) || 0.5
+          if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+            reported.add(el)
+            observer.unobserve(el)
+
+            var data = el._trackExposureData || {}
+            var adapter = tracker.getAdapter()
+            tracker.track('exposure', {
+              trackId:
+                (el.dataset && el.dataset.trackId) || data.id || undefined,
+              trackName:
+                (el.dataset && el.dataset.trackName) ||
+                data.name ||
+                undefined,
+              text: (el.innerText || '').trim().substring(0, 50),
+              xpath: adapter.getXPath(el),
+              visibleRatio: entry.intersectionRatio,
+              customData: data,
+            })
+          }
+        }
+      })
+    }
+
+    // 计算阈值
+    var thresholds
+    if (config && config.useDuration) {
+      thresholds = [0, config.exitRatio || 0.7, 1.0]
+    } else {
+      thresholds = [(config && config.threshold) || 0.5]
+    }
+
+    return {
+      bind: function (el, binding) {
+        el._trackExposureData = binding.value || {}
+
+        var observer = new IntersectionObserver(handleIntersection, {
+          root: null,
+          rootMargin: '0px',
+          threshold: thresholds,
+        })
+        observer.observe(el)
+        observers.set(el, observer)
+      },
+
+      update: function (el, binding) {
+        if (binding.value) {
+          el._trackExposureData = binding.value
+        }
+      },
+
+      unbind: function (el) {
+        var observer = observers.get(el)
+        if (observer) {
+          observer.unobserve(el)
+          observers.delete(el)
+        }
+        reported.delete(el)
+        // 清除可能存在的计时器
+        var tid = entryTimers.get(el)
+        if (tid) {
+          clearTimeout(tid)
+          entryTimers.delete(el)
+        }
+        delete el._trackExposureData
+      },
+    }
+  }
+
+  destroy() {
+    if (this._intersectionObserver) {
+      this._intersectionObserver.disconnect()
+      this._intersectionObserver = null
+    }
+    if (this._mutationObserver) {
+      this._mutationObserver.disconnect()
+      this._mutationObserver = null
+    }
+    // 清除所有待执行的计时器
+    this._entryTimers = null
+    this._observers = null
+    this._reported = null
+    this.tracker = null
+  }
+}

package/plugins/js-error.js

@@ -0,0 +1,232 @@
+export class JsErrorPlugin {
+  constructor() {
+    this.name = 'js-error'
+    this.tracker = null
+    this._errorHandler = null
+    this._rejectionHandler = null
+    this._recentErrors = {}
+    this._errorCount = 0
+    this._maxErrorsPerSession = 50
+    this._dedupWindowMs = 10000
+  }
+
+  install(tracker) {
+    this.tracker = tracker
+    var adapter = tracker.getAdapter()
+    var platform = adapter.getPlatformName()
+    var self = this
+
+    if (platform === 'web' || platform === 'app') {
+      this._errorHandler = function (event) {
+        if (event.target && event.target !== window && event.target.tagName) {
+          self._handleResourceError(event)
+        } else {
+          self._handleError(event)
+        }
+      }
+      this._rejectionHandler = function (event) {
+        self._handleRejection(event)
+      }
+
+      adapter.addErrorListener(this._errorHandler)
+      adapter.addUnhandledRejectionListener(this._rejectionHandler)
+    } else if (platform === 'weapp') {
+      this._errorHandler = function (errMsg) {
+        self._handleWeappError(errMsg)
+      }
+      adapter.addErrorListener(this._errorHandler)
+    }
+  }
+
+  /**
+   * Vue.config.errorHandler 调用入口
+   * 由 index.js install() 中注册，捕获 Vue 组件 render/lifecycle/watch 中的错误
+   */
+  handleVueError(err, vm, info) {
+    if (!this.tracker || !err) return
+
+    var message = err.message || String(err)
+    var stack = err.stack ? err.stack.substring(0, 1000) : ''
+    var componentName = ''
+
+    if (vm) {
+      var options = vm.$options || {}
+      componentName = options.name || options.__file || (options._componentTag) || ''
+      if (!componentName && vm.$parent) {
+        componentName = '(anonymous component)'
+      }
+    }
+
+    var fingerprint = 'vue|' + message + '|' + componentName + '|' + (info || '')
+
+    if (this._isDuplicate(fingerprint)) return
+    if (!this._shouldReport()) return
+
+    this.tracker.track('js_error', {
+      eventName: 'vue_error',
+      errorMessage: message,
+      errorStack: stack,
+      extraData: {
+        type: 'vue',
+        componentName: componentName,
+        lifecycleHook: info || '',
+        route: this._getCurrentRoute(),
+        referrer: this._getReferrer(),
+      }
+    })
+  }
+
+  _isDuplicate(fingerprint) {
+    var now = Date.now()
+    var last = this._recentErrors[fingerprint]
+    if (last && now - last < this._dedupWindowMs) return true
+    this._recentErrors[fingerprint] = now
+
+    var keys = Object.keys(this._recentErrors)
+    if (keys.length > 100) {
+      var cutoff = now - this._dedupWindowMs
+      for (var i = 0; i < keys.length; i++) {
+        if (this._recentErrors[keys[i]] < cutoff) {
+          delete this._recentErrors[keys[i]]
+        }
+      }
+    }
+    return false
+  }
+
+  _shouldReport() {
+    if (this._errorCount >= this._maxErrorsPerSession) return false
+    this._errorCount++
+    return true
+  }
+
+  _getCurrentRoute() {
+    try {
+      return this.tracker._currentPage || this.tracker.getAdapter().getCurrentPagePath() || ''
+    } catch (e) {
+      return ''
+    }
+  }
+
+  _getReferrer() {
+    try {
+      return this.tracker._referrer || ''
+    } catch (e) {
+      return ''
+    }
+  }
+
+  _handleError(event) {
+    if (!this.tracker || !event) return
+
+    var message = event.message || String(event)
+    var stack = (event.error && event.error.stack) ? event.error.stack.substring(0, 1000) : ''
+
+    // 跨域脚本报错：浏览器出于安全屏蔽详情，message 固定为 "Script error."
+    // 且 filename/lineno/stack 全空，无任何定位价值 → 丢弃，避免污染错误统计
+    if (/^script error\.?$/i.test(message) && !event.filename && !stack) {
+      return
+    }
+
+    var fingerprint = message + '|' + (event.filename || '') + '|' + (event.lineno || 0)
+
+    if (this._isDuplicate(fingerprint)) return
+    if (!this._shouldReport()) return
+
+    this.tracker.track('js_error', {
+      eventName: 'runtime_error',
+      errorMessage: message,
+      errorStack: stack,
+      extraData: {
+        type: 'runtime',
+        filename: event.filename || '',
+        lineno: event.lineno || 0,
+        colno: event.colno || 0,
+        route: this._getCurrentRoute(),
+        referrer: this._getReferrer(),
+      }
+    })
+  }
+
+  _handleRejection(event) {
+    if (!this.tracker || !event) return
+
+    var reason = event.reason || event
+    var message = reason ? (reason.message || String(reason)) : 'Unknown rejection'
+    var stack = (reason && reason.stack) ? reason.stack.substring(0, 1000) : ''
+    var fingerprint = 'rejection|' + message
+
+    if (this._isDuplicate(fingerprint)) return
+    if (!this._shouldReport()) return
+
+    this.tracker.track('js_error', {
+      eventName: 'unhandled_rejection',
+      errorMessage: message,
+      errorStack: stack,
+      extraData: {
+        type: 'unhandledRejection',
+        route: this._getCurrentRoute(),
+        referrer: this._getReferrer(),
+      }
+    })
+  }
+
+  _handleResourceError(event) {
+    if (!this.tracker || !event || !event.target) return
+
+    var el = event.target
+    var tagName = (el.tagName || '').toLowerCase()
+    var resourceUrl = el.src || el.href || ''
+
+    if (!resourceUrl) return
+
+    var fingerprint = 'resource|' + tagName + '|' + resourceUrl
+    if (this._isDuplicate(fingerprint)) return
+    if (!this._shouldReport()) return
+
+    this.tracker.track('js_error', {
+      eventName: 'resource_error',
+      errorMessage: tagName + ' load failed: ' + resourceUrl,
+      extraData: {
+        type: 'resource',
+        tagName: tagName,
+        resourceUrl: resourceUrl,
+        route: this._getCurrentRoute(),
+      }
+    })
+  }
+
+  _handleWeappError(errMsg) {
+    if (!this.tracker) return
+
+    var message = typeof errMsg === 'string' ? errMsg.substring(0, 1000) : String(errMsg)
+    var fingerprint = 'weapp|' + message
+
+    if (this._isDuplicate(fingerprint)) return
+    if (!this._shouldReport()) return
+
+    this.tracker.track('js_error', {
+      eventName: 'weapp_error',
+      errorMessage: message,
+      extraData: {
+        type: 'weapp',
+        route: this._getCurrentRoute(),
+      }
+    })
+  }
+
+  destroy() {
+    if (typeof window !== 'undefined') {
+      if (this._errorHandler) {
+        window.removeEventListener('error', this._errorHandler, true)
+      }
+      if (this._rejectionHandler) {
+        window.removeEventListener('unhandledrejection', this._rejectionHandler)
+      }
+    }
+    this._errorHandler = null
+    this._rejectionHandler = null
+    this.tracker = null
+    this._recentErrors = {}
+  }
+}

package/plugins/page-stay.js

@@ -0,0 +1,44 @@
+/**
+ * 页面停留时长插件
+ * 作为独立插件提供额外的停留追踪能力
+ * 注意：核心的页面停留 mixin 已在 compat.js 的 createPageStayMixin 中实现
+ * 本插件提供的是 H5 端基于 visibilitychange 的补充监听
+ */
+export class PageStayPlugin {
+  constructor() {
+    this.name = 'page-stay'
+    this.tracker = null
+    this._beforeUnloadHandler = null
+  }
+
+  install(tracker) {
+    this.tracker = tracker
+    var adapter = tracker.getAdapter()
+
+    if (adapter.supportsDOM()) {
+      this._setupVisibilityTracking()
+    }
+  }
+
+  _setupVisibilityTracking() {
+    if (typeof document === 'undefined') return
+
+    var self = this
+
+    // beforeunload 确保关闭标签页时强制同步刷新
+    if (typeof window !== 'undefined') {
+      this._beforeUnloadHandler = function () {
+        self.tracker.getQueue().flushSync()
+      }
+      window.addEventListener('beforeunload', this._beforeUnloadHandler)
+    }
+  }
+
+  destroy() {
+    if (this._beforeUnloadHandler && typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', this._beforeUnloadHandler)
+    }
+    this._beforeUnloadHandler = null
+    this.tracker = null
+  }
+}