Sunda Tracker

轻量级前端埋点 SDK，支持用户行为采集和性能监控。支持 API 和 Elasticsearch 两种数据上报方式，内置离线缓存、批量发送和失败重试。

安装

npm install sunda-tracker
# 或
yarn add sunda-tracker

需要同时安装 peer dependency：

npm install axios

快速开始

原生 JavaScript

import initTracker from 'sunda-tracker'

const tracker = initTracker({
  type: 'api',
  collectUrl: 'https://analytics.example.com/collect',
  collectMethod: 'post'
})

// 手动埋点
tracker.track('button_click', { buttonId: 'submit', page: 'home' })

// 设置用户信息
tracker.setUser({ userId: '12345', role: 'admin' })

// 清除用户信息
tracker.clearUser()

Vue 3

import { createApp } from 'vue'
import { VueTracker } from 'sunda-tracker'
import App from './App.vue'

const app = createApp(App)

app.use(VueTracker, {
  type: 'api',
  collectUrl: 'https://analytics.example.com/collect'
})

app.mount('#app')

组件中使用：

<script>
export default {
  methods: {
    handleClick() {
      this.$track.track('button_click', { buttonId: 'submit' })
    }
  },
  mounted() {
    this.$track.setUser({ userId: '12345' })
  }
}
</script>

Vue 2

import Vue from 'vue'
import { VueTracker } from 'sunda-tracker'

Vue.use(VueTracker, {
  type: 'api',
  collectUrl: 'https://analytics.example.com/collect'
})

组件中使用方式与 Vue 3 相同，通过 this.$track 访问。

React

SDK 不绑定 React，推荐用 Context 封装：

import { createContext, useContext, ReactNode } from 'react'
import initTracker from 'sunda-tracker'

const tracker = initTracker({
  type: 'api',
  collectUrl: 'https://analytics.example.com/collect'
})

const TrackContext = createContext(tracker)

export const TrackProvider = ({ children }: { children: ReactNode }) => (
  <TrackContext.Provider value={tracker}>{children}</TrackContext.Provider>
)

export const useTracker = () => useContext(TrackContext)

组件中使用：

import { useTracker } from './TrackContext'

function MyButton() {
  const tracker = useTracker()

  return (
    <button onClick={() => tracker.track('click', { id: 'my-btn' })}>
      提交
    </button>
  )
}

HTML 声明式埋点

开启 autoTrack 后，可通过 data-track-* 属性声明式埋点：

<button
  data-track-type="button_click"
  data-track-args-code="submit"
  data-track-args-page="home"
>
  提交
</button>

SDK 会自动监听点击事件，提取 data-track-type 作为事件名，data-track-args-* 作为事件参数（自动转为驼峰命名）。

配置项

| 选项 | 类型 | 默认值 | 说明 | | ------------------- | --------------- | -------- | -------------------------------------- | | type | 'api' \| 'es' | 'api' | 上报方式：API 接口或直连 Elasticsearch | | collectUrl | string | '' | API 模式的上报地址 | | collectMethod | string | 'post' | API 模式的请求方法 | | autoTrack | boolean | false | 是否开启自动埋点（点击事件） | | enablePerformance | boolean | false | 是否开启性能监控 | | batchSize | number | 100 | 批量发送阈值 | | flushInterval | number | 5000 | 自动刷新间隔（ms） | | serverUrl | string | '' | 服务器地址 | | appId | string | '' | 应用标识 | | debug | boolean | false | 调试模式 | | maxRetryTimes | number | 3 | 失败重试次数 | | timeout | number | 5000 | 请求超时（ms） |

ES 模式额外配置：

| 选项 | 类型 | 说明 | | --------- | -------- | ---------------------------- | | node | string | Elasticsearch 服务器地址 | | index | string | 索引名称（自动按日期分索引） | | encoded | string | API Key（base64 编码） |

API

| 方法 | 说明 | | ------------------------------ | ------------------------------------- | | track(eventName, eventData?) | 上报埋点事件 | | setUser(userInfo) | 设置用户信息（持久化到 localStorage） | | clearUser() | 清除用户信息 | | destroy() | 销毁实例，持久化未发送数据并清理资源 |

特性

• 批量发送：数据攒够 batchSize 条或每隔 flushInterval 自动发送
• 离线缓存：离线时数据暂存内存，页面关闭前持久化到 localStorage，恢复在线后自动发送
• 失败重试：发送失败的数据存入 localStorage，最多重试 3 次
• 性能监控：开启后自动采集页面加载、资源加载、长任务、Paint Timing、JS 错误和 Promise 异常
• 设备信息：自动采集 OS、浏览器、屏幕、网络、硬件等信息
• TypeScript：完整类型支持，构建产物包含 .d.ts 声明文件

开发

# 安装依赖
yarn install

# 开发
yarn dev

# 构建（含类型检查）
yarn build

# 代码检查
yarn eslint
yarn prettier

许可证

MIT