前端埋点 SDK

一个功能完整的前端埋点SDK，支持异常捕获、用户行为追踪、性能监控和第三方埋点集成。

功能特性

- 🔍 异常拦截: 自动捕获 JavaScript 错误、Promise 拒绝、资源加载错误
- 📊 事件追踪: 自动追踪页面浏览、点击事件，支持自定义事件
- 📈 性能监控: 监控首屏加载时间、白屏时间、HTTP请求响应时间、页面渲染时间
- 👤 用户行为追踪: 追踪页面停留时间、滚动行为、表单交互、鼠标移动、键盘输入
- 🚀 批量上报: 支持批量上报，减少网络请求
- 🔧 灵活配置: 支持多种上报方式和第三方埋点
- 🛡️ 错误处理: 完善的错误处理和重试机制
- 📦 轻量级: 体积小，性能优秀
- 🔗 第三方集成: 支持百度统计、友盟统计、神策数据、腾讯云分析、Google Analytics等

安装

``bash
npm install bw-frontend-sdk
`

注意: 本SDK优先使用 sendBeacon API 发送HTTP请求（性能更好、异步非阻塞），axios 仅作为候补方案（当 sendBeacon 不可用、失败或数据过大时使用）。SDK 会自动安装 axios 依赖作为候补。

快速开始

$3

`javascript
import FrontendSDK from 'bw-frontend-sdk'

const sdk = new FrontendSDK({
appId: 'your-app-id',
reportUrl: 'https://your-api.com/report',
enableErrorTracking: true,
enableEventTracking: true
})
`

$3

#### 选项式API

`javascript
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import FrontendSDK from 'bw-frontend-sdk'

const app = createApp(App)

// 初始化 SDK
const sdk = new FrontendSDK({
appId: 'your-app-id',
reportUrl: 'https://your-api.com/report'
})

// 全局注册
app.config.globalProperties.$sdk = sdk

// 全局错误处理
app.config.errorHandler = (error, instance, info) => {
sdk.reportError(error, {
component: instance?.$options?.name,
info: info
})
}

app.mount('#app')
`

#### 组合式API

`javascript
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import FrontendSDK from 'bw-frontend-sdk'

const app = createApp(App)

// 初始化 SDK
const sdk = new FrontendSDK({
appId: 'your-app-id',
reportUrl: 'https://your-api.com/report'
})

// 全局注册
app.config.globalProperties.$sdk = sdk

// 全局错误处理
app.config.errorHandler = (error, instance, info) => {
sdk.reportError(error, {
component: instance?.$options?.name,
info: info
})
}

app.mount('#app')
`

$3

#### 选项式API

`javascript
export default {
data() {
return {
mountStartTime: Date.now()
}
},
mounted() {
// 上报页面浏览
this.$sdk.reportEvent('page_view', {
page: 'home',
title: '首页'
})

// 上报组件挂载性能
this.$sdk.reportPerformance({
componentMountTime: Date.now() - this.mountStartTime,
component: 'HomePage'
})
},
methods: {
handleClick() {
// 上报点击事件
this.$sdk.reportEvent('button_click', {
buttonId: 'submit',
action: 'submit_form'
})
},
handleError() {
// 上报错误
this.$sdk.reportError(new Error('操作失败'), {
page: 'form',
action: 'submit'
})
}
}
}
`

#### 组合式API

`javascript
import { ref, onMounted, getCurrentInstance } from 'vue'

export default {
setup() {
const mountStartTime = ref(Date.now())
const { proxy } = getCurrentInstance()

onMounted(() => {
// 上报页面浏览
proxy.$sdk.reportEvent('page_view', {
page: 'home',
title: '首页'
})

// 上报组件挂载性能
proxy.$sdk.reportPerformance({
componentMountTime: Date.now() - mountStartTime.value,
component: 'HomePage'
})
})

const handleClick = () => {
// 上报点击事件
proxy.$sdk.reportEvent('button_click', {
buttonId: 'submit',
action: 'submit_form'
})
}

const handleError = () => {
// 上报错误
proxy.$sdk.reportError(new Error('操作失败'), {
page: 'form',
action: 'submit'
})
}

return {
handleClick,
handleError
}
}
}
`

配置选项

`javascript
const config = {
// 基础配置
appId: 'your-app-id', // 应用ID
appVersion: '1.0.0', // 应用版本
environment: 'production', // 环境

// 上报配置
reportUrl: 'https://api.com/report', // 上报地址
reportInterval: 5000, // 批量上报间隔(ms)
maxQueueSize: 100, // 最大队列大小

// 错误追踪配置
enableErrorTracking: true, // 启用错误追踪
enableUnhandledRejection: true, // 启用未处理Promise拒绝追踪
enableResourceError: true, // 启用资源错误追踪

// 事件追踪配置
enableEventTracking: true, // 启用事件追踪
enableClickTracking: true, // 启用点击追踪
enablePageViewTracking: true, // 启用页面浏览追踪

// 性能监控配置
enablePerformanceTracking: true, // 启用性能监控
enableResourceTracking: true, // 启用资源加载监控
enableApiTracking: true, // 启用API请求监控
enableInteractionTracking: true, // 启用用户交互性能监控

// 用户行为追踪配置
enableUserInteractionTracking: true, // 启用用户交互追踪
enableFormTracking: true, // 启用表单行为追踪
enableScrollTracking: true, // 启用滚动行为追踪
enableMouseTracking: false, // 启用鼠标移动追踪（可选）
enableKeyboardTracking: false, // 启用键盘输入追踪（可选）

// 第三方埋点配置
thirdPartyConfig: {
baidu: {
enabled: true,
siteId: 'your-baidu-site-id',
autoPageview: true
}, // 百度统计
umeng: {
enabled: true,
siteId: 'your-umeng-site-id',
autoPageview: true
}, // 友盟统计
sensors: {
enabled: true,
serverUrl: 'https://your-sensors-server.com',
siteId: 'your-sensors-site-id',
autoPageview: true
}, // 神策数据
tencent: {
enabled: true,
appId: 'your-tencent-app-id',
autoPageview: true
}, // 腾讯云分析
google: {
enabled: true,
measurementId: 'G-XXXXXXXXXX',
autoPageview: true
}, // Google Analytics
custom: { // 自定义第三方
enabled: true,
init: (config) => {
// 自定义第三方SDK初始化逻辑
return {
track: (eventName, data) => { / 追踪事件 / },
trackPageview: (data) => { / 追踪页面浏览 / },
setUser: (userData) => { / 设置用户信息 / },
trackPerformance: (data) => { / 追踪性能指标 / }
}
}
}
},

// 自定义上报函数
customReport: async (type, data) => {
// 自定义上报逻辑
}
}
`

API 参考

$3

#### 构造函数

`javascript
new FrontendSDK(options)
`

#### 方法

- reportError(error, context): 手动上报错误
- reportEvent(eventName, data): 手动上报事件
- reportPerformance(metrics): 手动上报性能指标
- reportBehavior(eventName, data): 手动上报用户行为
- setUser(userInfo): 设置用户信息
- setConfig(config): 更新配置
- getPerformanceMetrics(): 获取当前性能指标
- getBehaviorData(): 获取用户行为数据
- getSessionId(): 获取当前会话ID
- isThirdPartySDKIntegrated(sdkName): 检查第三方SDK是否已集成
- getIntegratedThirdPartySDKs(): 获取已集成的第三方SDK列表
- destroy(): 销毁 SDK

$3

- javascript: JavaScript 错误
- unhandledrejection: 未处理的 Promise 拒绝
- resource: 资源加载错误
- click: 点击事件
- pageview: 页面浏览事件
- custom: 自定义事件
- performance: 性能指标
- behavior: 用户行为
- page_stay: 页面停留时间
- slow_resource: 慢资源加载
- slow_api: 慢API请求

性能监控

SDK 提供全面的性能监控功能，包括：

1. 页面性能: 监控页面加载时间、Web Vitals 等核心指标
2. 资源监控: 监控静态资源加载性能
3. API监控: 监控接口请求性能
4. 路由监控: 监控 Vue Router 路由跳转的页面浏览时间
5. 用户交互: 监控用户交互性能指标

$3

专门为 Vue 3 应用提供路由跳转监控，准确计算页面停留时间：

`javascript
// 初始化 SDK 后设置路由监控
const sdk = new FrontendSDK({
enablePerformanceTracking: true
})

// 设置 Vue Router 监控
sdk.setupVueRouterMonitoring(router)

// 获取当前页面停留时间
const stayTime = sdk.getCurrentPageStayTime()

// 获取路由性能统计
const routeStats = sdk.getRoutePerformanceStats()

// 获取路由历史
const routeHistory = sdk.getRouteHistory()
`

功能特性：
- ✅ 监控路由跳转（进入/离开）
- ✅ 准确计算页面停留时间
- ✅ 记录完整的路由历史
- ✅ 提供路由性能统计
- ✅ 自动上报性能数据

详细使用说明请参考：Vue 3 路由监控使用指南

用户行为追踪

SDK 自动追踪以下用户行为：

- 页面浏览: 页面访问、路由变化、访问来源
- 点击行为: 点击、双击、右键点击、触摸事件
- 表单交互: 表单提交、字段变化、聚焦失焦
- 滚动行为: 滚动深度、滚动位置
- 鼠标移动: 鼠标轨迹（可选）
- 键盘输入: 按键事件（可选）
- 页面停留时间: 用户在页面的停留时长

第三方埋点支持

$3

`javascript
// 在 HTML 中引入百度统计

`

$3

`javascript
// 在 HTML 中引入友盟统计

`

$3

`javascript
// 在 HTML 中引入神策数据

`

$3

`javascript
// 在 HTML 中引入 Google Analytics


`

完整使用示例

`javascript
import FrontendSDK from 'bw-frontend-sdk'

// 初始化SDK
const sdk = new FrontendSDK({
appId: 'your-app-id',
reportUrl: 'https://your-api.com/report',

// 启用所有功能
enableErrorTracking: true,
enableEventTracking: true,
enablePerformanceTracking: true,
enableUserInteractionTracking: true,
enableFormTracking: true,
enableScrollTracking: true,

// 第三方埋点配置
thirdPartyConfig: {
baidu: {
enabled: true,
siteId: 'your-baidu-site-id'
},
google: {
enabled: true,
measurementId: 'G-XXXXXXXXXX'
}
}
})

// 设置用户信息
sdk.setUser({
userId: 'user123',
userName: '张三',
userType: 'vip'
})

// 手动上报事件
sdk.reportEvent('button_click', {
buttonId: 'submit-btn',
buttonText: '提交'
})

// 手动上报性能指标
sdk.reportPerformance({
customMetric: 'custom_value',
pageLoadTime: 1500
})

// 手动上报用户行为
sdk.reportBehavior('form_start', {
formId: 'login-form',
formType: 'login'
})

// 获取性能指标
const metrics = sdk.getPerformanceMetrics()
console.log('性能指标:', metrics)

// 获取用户行为数据
const behaviorData = sdk.getBehaviorData()
console.log('行为数据:', behaviorData)

// 检查第三方SDK集成状态
const isGoogleIntegrated = sdk.isThirdPartySDKIntegrated('google')
console.log('Google Analytics集成状态:', isGoogleIntegrated)
`

构建

`bash


安装依赖

npm install

构建

npm run build

开发模式

npm run dev
`

数据上报机制

SDK 采用智能上报策略，优先使用现代浏览器 API，自动降级保证兼容性：

$3

1. sendBeacon（主要方式）
- ✅ 异步非阻塞，不影响页面性能
- ✅ 页面卸载时仍能可靠发送（重要数据不丢失）
- ✅ 性能更好，不占用主线程
- ✅ 自动处理，无需额外配置
- ⚠️ 数据大小限制约 60KB（超过时自动使用 axios）

2. axios（候补方案）
- 🔄 当 sendBeacon 不可用、失败或数据过大时自动使用
- 🔄 支持更大的数据量
- 🔄 兼容所有浏览器环境

$3

`javascript
// SDK 会自动选择最佳上报方式
const sdk = new FrontendSDK({
reportUrl: 'https://your-api.com/report'
})

// 优先尝试 sendBeacon，失败或不可用时自动使用 axios
sdk.reportEvent('user_action', { action: 'click' })
`

$3

当 SDK 使用 axios 作为候补方案时，可以使用自定义配置：

`javascript
// 导入 axios 实例（仅在 axios 作为候补时使用）
import axiosInstance from 'bw-frontend-sdk/axios-config'

// 自定义配置（仅在 axios 作为候补时生效）
axiosInstance.defaults.baseURL = 'https://api.example.com'
axiosInstance.defaults.timeout = 15000
``

相关文档

- Vue 3 组合式API使用指南 - 详细的组合式API使用说明
- Axios集成说明 - axios集成的详细说明
- 实现总结 - SDK功能的完整总结

许可证

MIT