Web Tracker Simple

一个简单的 Web 埋点工具，支持页面访问、点击事件等基础埋点功能。

功能特点

• 📊 页面访问（PV）统计
• 👆 点击事件跟踪
• 📱 设备信息收集
• 👤 用户行为分析
• 📝 自定义数据上报
• 📌 自定义页面标题
• 🛣 路由变化监听
• 🔄 防重复上报

安装

npm install @koi-br/web-tracker-simple

使用示例

基础配置

import Tracker from '@koi-br/web-tracker-simple';

const tracker = Tracker({
  appId: 'your-app-id',
  endpoint: 'your-endpoint',
  debug: true
});

使用子类

如果需要直接访问各个子类：

import Tracker from '@koi-br/web-tracker-simple';

// 获取子类引用
const { PageTracker, ClickTracker } = Tracker;

// 使用工厂函数创建跟踪器实例
const tracker = Tracker({
  appId: 'your-app-id',
  endpoint: 'your-endpoint'
});

动态设置自定义数据

// 设置自定义数据
tracker.setCustomData({
  userId: '123',
  userType: 'vip',
  customField: 'customValue'
});

// 获取当前自定义数据
const currentData = tracker.getCustomData();

动态设置页面标题

// 设置自定义页面标题
tracker.setCustomTitle('自定义页面标题');

// 获取当前自定义标题
const currentTitle = tracker.getCustomTitle();

设置用户ID

tracker.setUserId('user-123');

初始化路由（Vue Router）

import { createRouter } from 'vue-router';

const router = createRouter({
  // 你的路由配置
});

tracker.initRouter(router);

点击事件跟踪

在 HTML 元素上添加 data-track-id 属性来跟踪点击事件：

<button data-track-id="submit-button">提交</button>

可以添加自定义数据属性：

<button 
  data-track-id="submit-button"
  data-custom-user-type="vip"
  data-custom-action="submit"
>
  提交
</button>

配置选项

interface TrackerConfig {
  appId: string;         // 应用ID（必填）
  endpoint?: string;     // 上报地址
  debug?: boolean;       // 是否开启调试模式
  sampleRate?: number;   // 采样率 0-1
  maxBatchSize?: number; // 批量上报大小
  maxWaitTime?: number;  // 最大等待时间(ms)
  customData?: Record<string, any>;  // 自定义数据
  customTitle?: string;  // 自定义页面标题
}

事件数据格式

页面访问事件

interface PageViewData {
  title: string;         // 页面标题
  url: string;          // 页面URL
  referrer: string;     // 来源页面
  timestamp: number;    // 时间戳
  pageKey: string;      // 页面标识
  isFirst: boolean;     // 是否首次访问
}

点击事件

interface ClickEventData {
  trackId: string;      // 跟踪ID
  elementType: string;  // 元素类型
  elementText: string;  // 元素文本
  title: string;        // 页面标题
  url: string;         // 页面URL
  pageKey: string;     // 页面标识
  // ... 其他自定义数据
}

注意事项

1. 确保在使用前设置正确的 appId 和 endpoint
2. 建议在开发环境开启 debug 模式以便调试
3. 自定义数据属性名需要使用 data-custom- 前缀
4. 页面标题获取优先级：路由 meta > 自定义标题 > document.title
5. 设备ID会在本地存储中保存，用于用户识别

License

MIT

Author

dekun.tang