@haimashale/tracker

Vue3 Tracker SDK

基于 localStorage 和 Axios 的前端监控 SDK，支持埋点、异常捕获及自动上报。

特性

• 本地持久化：所有数据存储在 localStorage，刷新不丢失。
• 接口分离：埋点和异常使用独立接口。
• 自动上报：累计10条或每分钟自动上报，成功后才删除缓存。
• Vue3 插件：开箱即用。
• 相同数据去重：新增数据与缓存中最后一条完全一致时自动丢弃（避免渲染循环等场景的重复数据刷屏）。
• 缓存上限保护：单类缓存（埋点 / 异常各自独立）超出上限后丢弃最旧数据，即使上报接口持续失败也不会无限膨胀、导致页面卡顿。
• 防抖优化：持久化写入与上报调度均做防抖合并；并采用内存镜像，避免每次新增都整体解析 / 序列化 localStorage，显著降低高频新增时的性能开销。
• 上报兜底：上报失败时保留缓存等待下次重试，并避免未捕获异常。

安装

# 项目根目录下运行
npm i @haimashale/tracker

快速开始

1. 注册插件

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import Tracker from 'tracker';
createApp(App)
  .use(Tracker, {
    endpoints: {
      trackUrl: 'https://api.example.com/track', // 埋点接口
      errorUrl: 'https://api.example.com/error'  // 异常接口
    },
    operatorKey: 'userName', // 用户名称  缓存中取（user.userName）
    subjectKey: 'mainName',  // 主体名称  缓存中取（user.mainName）
  })
  .mount('#app');

2. 手动埋点

import { trackClick, trackQuery } from 'tracker';
trackClick('事件名称', '/api/order', { amount: 99 }, '提交订单');
trackQuery('查询用户事件', '/api/users', { keyword: '张三' });

3. 手动上报（可选）

import { manualReport } from 'tracker';
manualReport();

API

初始化配置项

{
    operatorKey: 'userName', // localStorage 中用户标识字段
    subjectKey: 'mainName', // localStorage 中主体名称字段
    endpoints: {
        trackUrl: '', // 埋点上报接口
        errorUrl: '' // 异常上报接口
    },
    // ↓↓↓ 以下为可选优化配置（含默认值） ↓↓↓
    enableTrack: true,   // 总开关：false 时 trackClick/trackQuery/trackError 及自动错误捕获既不写缓存也不上报
    maxCacheSize: 50,    // 单类缓存上限（埋点 / 异常各自独立计），超出丢弃最旧数据
    saveDebounce: 500,   // 持久化防抖间隔（毫秒），合并短时间内的多次 localStorage 写入
    flushDebounce: 1000  // 上报调度防抖间隔（毫秒），合并触发避免上报风暴
}

相同数据去重说明

• 新增数据与对应缓存数组的最后一条数据做比对，字段完全一致则丢弃、不写入缓存。
• trackClick / trackQuery（埋点）比对字段：beaconType, beaconName, beaconUrl, beaconParams, remark
• trackError（异常）比对字段：exceptionName, occurUrl, exceptionMsg, remark
• 对象 / 数组字段（如 beaconParams）按序列化结果比较。
• 若两条相同数据之间夹了不同数据，则仍会各自保留（按"仅与最后一条对比"的规则）。