前端埋点 SDK

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

功能特性

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

安装

npm install bw-frontend-sdk

注意: 本SDK使用axios进行所有HTTP请求，会自动安装axios依赖。

快速开始

基础使用

import FrontendSDK from 'bw-frontend-sdk'

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

Vue 3 集成

选项式API

// 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

// 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

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

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
    }
  }
}

配置选项

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 参考

FrontendSDK

构造函数

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

事件类型

• 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. 用户交互: 监控用户交互性能指标

路由监控（Vue Router）

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

// 初始化 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 自动追踪以下用户行为：

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

第三方埋点支持

百度统计

// 在 HTML 中引入百度统计
<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?YOUR_SITE_ID";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

友盟统计

// 在 HTML 中引入友盟统计
<script>
(function() {
  var um = document.createElement('script');
  um.src = 'https://s4.cnzz.com/z_stat.php?id=YOUR_SITE_ID&web_id=YOUR_SITE_ID';
  var s = document.getElementsByTagName('script')[0];
  s.parentNode.insertBefore(um, s);
})();
</script>

神策数据

// 在 HTML 中引入神策数据
<script>
!function(e,t,n,s,a,c,i){e[s]=e[s]||function(){(e[s].q=e[s].q||[]).push(arguments)},a=t.createElement(n),c=t.getElementsByTagName(n)[0],a.async=1,a.src="https://www.sensorsdata.cn/sdk.js",c.parentNode.insertBefore(a,c)}(window,document,"script","sensors");
sensors.init("YOUR_SITE_ID");
</script>

Google Analytics

// 在 HTML 中引入 Google Analytics
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

完整使用示例

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)

构建

# 安装依赖
npm install

# 构建
npm run build

# 开发模式
npm run dev

Axios集成

SDK默认使用axios进行所有HTTP请求，包括：

1. 数据上报: 自动使用axios发送数据到后端
2. 性能监控: 自动监控所有axios请求的性能
3. 错误处理: 统一的axios错误处理机制

使用内置axios实例

// SDK会自动使用axios进行所有网络请求
const sdk = new FrontendSDK({
  reportUrl: 'https://your-api.com/report'
})

// 数据会自动通过axios上报
sdk.reportEvent('user_action', { action: 'click' })

使用自定义axios配置

// 如果需要自定义axios配置，可以导入axios实例
import axiosInstance from './axios-config'

// 自定义配置
axiosInstance.defaults.baseURL = 'https://api.example.com'
axiosInstance.defaults.timeout = 15000

// 发送请求
const response = await axiosInstance.post('/api/data', { key: 'value' })

相关文档

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

许可证

MIT