Web Tracking SDK

一个轻量级的前端埋点SDK，专注于页面访问、用户行为和性能数据的采集。支持自动采样、SPA应用和表单监控。

核心功能

1. 页面访问统计

• 🔄 PV/UV 统计
  • 页面浏览/进入/离开事件
  • 访客身份识别与追踪
  • 会话管理
  • 页面停留时长

2. 用户行为追踪

• 🖱️ 点击事件追踪
  • 重要按钮点击（提交、保存、删除等）
  • 外部链接点击
  • 可追踪元素点击
  • 点击位置与元素路径
• 📝 表单行为监控
  • 表单提交事件
  • 表单基础信息采集

3. 性能监控

• ⚡ 核心性能指标
  • First Contentful Paint (FCP)
  • Largest Contentful Paint (LCP)
  • 页面加载性能
  • DOM 准备时间

4. 智能采集策略

• 🎯 灵活的采样配置
• 🔍 重要行为优先采集
• 🌟 SPA 路由变化监听
• 🛡️ 防止重复采集

安装

npm install @koi-br/web-tracking-sdk

快速开始

import { initTracker } from '@koi-br/web-tracking-sdk';

const tracker = initTracker({
  appId: 'your-app-id',
  uploadUrl: 'https://your-api.com/collect',
  autoTrack: true,
  uploadInterval: 5000,
  projectId: 'your-project-id',
  maxCache: 50,
  sampling: {
    ratio: 0.5,                    // 采样率50%
    eventTypes: ['click_button']   // 指定采样事件类型
  }
});

事件类型

type EventType = 
  // 页面相关
  | 'page_view'      // 页面浏览
  | 'page_enter'     // 页面进入
  | 'page_leave'     // 页面离开
  | 'page_scroll'    // 页面滚动
  // 交互相关
  | 'click_button'   // 按钮点击
  | 'click_link'     // 链接点击
  | 'click_element'  // 元素点击
  | 'form_submit'    // 表单提交
  // 性能相关
  | 'performance'    // 性能数据
  // 用户相关
  | 'user_visit'     // 用户访问
  | 'user_engage'    // 用户参与
  | 'custom_event';  // 自定义事件

配置选项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | - | 应用标识 | | uploadUrl | string | - | 数据上报地址 | | autoTrack | boolean | false | 开启自动采集 | | uploadInterval | number | 5000 | 上报间隔(ms) | | maxCache | number | 50 | 本地缓存上限 | | sampling.ratio | number | 1 | 采样比例(0-1) | | sampling.eventTypes | string[] | - | 采样事件类型 |

特色功能

1. 智能按钮识别

• 支持通过文本内容识别重要按钮（如：提交、保存、删除等）
• 支持 role="button" 属性识别
• 支持自定义 data-track 属性标记

2. 链接点击过滤

• 自动过滤无效链接
• 排除锚点链接
• 支持 no-track 类名排除

3. SPA 支持

• 自动监听路由变化
• 准确记录页面切换
• 支持 History API

4. 访客追踪

• 唯一访客标识
• 新老访客区分
• 访问次数统计
• 会话管理

浏览器支持

• 现代浏览器 (Chrome, Firefox, Safari, Edge)
• 移动端浏览器
• 依赖 API: localStorage, MutationObserver, PerformanceObserver

License

MIT