etrackp 前端埋点监控 SDK

etrackp 是一个轻量级、高性能的前端行为与性能监控 SDK。它能够自动采集用户行为、页面性能、路由变化、HTTP 请求等数据，并提供灵活的上报机制和自定义扩展功能。

Admin Event Analysiss 配套用于展示网站的上报用户行为数据，包括页面浏览量（PV）、独立访客数（UV）、页面停留时长以及点击事件分布。

📦 安装

通过 NPM 安装

npm install etrackp

通过 CDN 引入

<script src="https://cdn.example.com/etrackp.umd.js"></script>

NPM 方式引入

import Etrackp from 'etrackp'
// 或
const Etrackp = require('etrackp');

🚀 快速开始

1. 基础用法

// 创建监控实例
const tracker = new Etrackp({
  url: 'https://your-api-domain.com/track' // 数据上报地址（必填）
});

// 初始化监控
tracker.init({
  observe_router: true,      // 监听路由变化
  observe_http: true,        // 监听 HTTP 请求
  observe_click: true,       // 监听点击事件
  observe_performance: true, // 监听性能指标
  user_id: 'optional_user_id' // 自定义用户 ID（可选）
});

2. 高级配置

const tracker = new Etrackp({
  url: 'https://api.yourdomain.com/analytics'
});

// 设置自定义字段
tracker.setOptions({
  project: 'website',
  version: '2.1.0',
  environment: 'production'
});

// 初始化监控
tracker.init({
  observe_router: true,
  observe_http: true,
  observe_click: true,
  observe_performance: true,
  user_id: 'user_123456'
});

// 自定义事件上报
tracker.customReporting({
  event: 'user_login',
  login_method: 'email',
  timestamp: Date.now()
});

✨ 核心功能

🔄 路由监控

• 自动监听 pushState / replaceState API 调用
• 监听浏览器前进/后退操作
• 自动计算页面停留时间
• 支持 SPA（单页应用）路由变化追踪

🌐 HTTP 请求监控

• 自动拦截 XMLHttpRequest 请求
• 自动拦截 fetch API 请求
• 记录请求方法、URL、请求体等信息
• 支持排除特定请求（通过 etrackpNoRecord: true）

🖱️ 点击事件监控

• 全局点击事件监听
• 智能采集元素信息（标签名、类名、文本内容）
• 记录点击坐标位置
• 支持配置需要采集文本的标签类型

📊 性能监控

• FP（First Paint）: 首次绘制时间
• FCP（First Contentful Paint）: 首次内容绘制时间
• LCP（Largest Contentful Paint）: 最大内容绘制时间及相关元素信息
• DCL（DOMContentLoaded）: DOM 加载完成时间
• Load: 页面完全加载时间
• TTFB（Time to First Byte）: 首字节时间

👤 用户识别

• 自动生成 UUID（符合 RFC4122 标准）
• 支持自定义用户 ID
• 基于 localStorage 的持久化存储
• 跨会话用户身份保持

📤 数据上报

• 智能缓存机制（默认 10 条批量上报）
• 页面卸载前自动上报剩余数据
• 支持自定义字段扩展
• 断网环境下数据持久化存储

📖 API 参考

构造函数

new Etrackp(options)

参数：

• options (Object): 配置对象
  • req_url (String, 必填): 数据上报地址例如 'https://api.yourdomain.com/analytics'

方法

init(observeConfig)

初始化监控器。

参数：

• observeConfig (Object): 监控配置
  • observe_router (Boolean): 是否监控路由变化
  • observe_http (Boolean): 是否监控 HTTP 请求
  • observe_click (Boolean): 是否监控点击事件
  • observe_performance (Boolean): 是否监控性能指标
  • user_id (String, 可选): 自定义用户 ID

示例：

tracker.init({
  observe_router: true,
  observe_http: true,
  observe_click: true,
  observe_performance: true,
  user_id: 'custom_user_id'
});

destroy()

销毁监控器，移除所有事件监听。

示例：

tracker.destroy();

customReporting(data)

上报自定义事件。

参数：

• data (Object): 事件数据对象，必须包含 event 字段
  • 自定义字段（只会当前上报携带字段）

示例：

tracker.customReporting({
  event: 'video_play',
  video_id: '12345',
  duration: 120,
  play_type: 'auto'
});

setOptions(data)

设置自定义字段或更新用户 ID。

参数：

• data (Object): 配置数据对象
  • user_id (String, 可选): 更新用户 ID
  • 其他自定义字段（所有事件都会携带setOptions的字段）

示例：

tracker.setOptions({
  user_id: 'new_user_id',
  project: 'ecommerce',
  page_type: 'product_detail',
  utm_source: 'google_ads'
});

removeOptions(key)

移除已添加的自定义字段

参数：

• key (String, 必填): 要移除的字段

示例：

tracker.removeOptions('your-custom-key');

📊 数据格式说明

通用字段

所有上报数据都包含以下基础字段：

| 字段名 | 类型 | 说明 | |--------|------|------| | origin | String | 页面来源（协议+域名+端口） | | uuid | String | 用户唯一标识 | | screen_height | Number | 屏幕高度（像素） | | screen_width | Number | 屏幕宽度（像素） | | scroll_top | Number | 页面滚动位置 | | timestamp | Number | 触发时的时间戳 | | custom_field | Object | 自定义字段集合 | | event | String | 事件类型标识 | | ua | String | 浏览器标识 | | network | String | 设备网络类型 | | href | String | 页面路径（相对路径） |

事件类型及字段

1. 点击事件 (elementClick)

| 字段 | 类型 | 说明 | |------|------|------| | node_type | Number | DOM 节点类型 | | tag_name | String | 元素标签名（小写） | | class_name | String | 元素类名 | | text_content | String | 元素文本内容（仅限配置的标签类型） | | client_x | Number | 点击位置 X 坐标 | | client_y | Number | 点击位置 Y 坐标 |

2. 路由变化 (routerChange)

| 字段 | 类型 | 说明 | |------|------|------| | type | String | 路由变化类型：pushState、replaceState、forwardOrBack | | from | String | 来源路径（相对路径） | | to | String | 目标路径（相对路径） |

3. 停留时间 (dwellTime)

| 字段 | 类型 | 说明 | |------|------|------| | stay_ms | Number | 停留时间（毫秒） |

4. HTTP 请求

XMLHttpRequest (reuqest): | 字段 | 类型 | 说明 | |------|------|------| | req_url | String | 请求 URL | | req_method | String | 请求方法 | | req_body | Object | 请求体数据 | | type | String | XMLHttpRequest |

Fetch (reuqest): | 字段 | 类型 | 说明 | |------|------|------| | req_url | String | 请求 URL | | req_method | String | 请求方法 | | req_credentials | String | 凭证模式 | | req_headers | Object | 请求头 | | req_params | Object | URL 参数 | | req_timeout | Number | 超时时间 | | type | String | fetch |

5. 性能指标 (page_performance)

| 字段 | 类型 | 说明 | |------|------|------| | fp | Number | 首次绘制时间（毫秒） | | fcp | Number | 首次内容绘制时间（毫秒） | | dcl | Number | DOMContentLoaded 时间（毫秒） | | page_load | Number | 页面加载完成时间（毫秒） | | ttfb | Number | 首字节时间（毫秒） | | lcp | Number | 最大内容绘制时间（毫秒） | | tag_name | String | LCP 对应元素的标签名 | | text_content | String | LCP 对应元素的文本内容 |

6. 自定义上报 (custom_reporting)

| 字段 | 类型 | 说明 | |------|------|------| | type | String | event值 | | custom_field | Object | 自定义上报字段集合 |

⚙️ 配置选项

默认配置

// SDK 内部默认值
{
  #hasTextTags: ['button', 'span', 'a'],  // 需要采集文本的标签类型
  #url: '',          // 上报地址-必填
  #uuidTemplate: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx' // UUID 模板
}

性能优化建议

1. 按需启用监控：只启用需要的监控功能
2. 自定义上报频率：调整上报阈值（修改代码中的 old_str_arr.length > 10）
3. 数据脱敏：通过 setOptions 设置自定义字段进行数据脱敏
4. 排除敏感请求：在 fetch 请求中添加 etrackpNoRecord: true

🔧 集成示例

Vue.js 集成

// main.js
import etrackp from 'etrackp';

const tracker = new Etrackp({
  url: process.env.VUE_APP_TRACK_URL
});

// 设置项目信息
tracker.setOptions({
  project: 'vue-app',
  version: process.env.VUE_APP_VERSION
});

// 初始化监控
tracker.init({
  observe_router: true,
  observe_http: false,
  observe_click: true,
  observe_performance: true
});

// 挂载到 Vue 实例
Vue.prototype.$tracker = tracker;

React 集成

// tracker.js
import etrackp from 'etrackp';

class Tracker {
  constructor() {
    this.tracker = new Etrackp({
      url: process.env.REACT_APP_TRACK_URL
    });
    
    this.tracker.setOptions({
      project: 'react-app',
      version: process.env.REACT_APP_VERSION
    });
  }
  
  init() {
    this.tracker.init({
      observe_router: true,
      observe_http: true,
      observe_click: true,
      observe_performance: true
    });
  }
  
  // 封装自定义事件
  trackEvent(eventName, properties) {
    this.tracker.customReporting({
      event: eventName,
      ...properties,
      timestamp: Date.now()
    });
  }
}

export default new Tracker();

// App.js
import tracker from './tracker';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    tracker.init();
    
    // 组件卸载时销毁
    return () => {
      tracker.tracker.destroy();
    };
  }, []);
  
  // 使用示例
  const handleButtonClick = () => {
    tracker.trackEvent('button_click', {
      button_id: 'submit_btn',
      page: 'home'
    });
  };
}

📈 数据处理建议

后端接收示例（Node.js）

const express = require('express');
const app = express();

app.use(express.json({ limit: '10mb' }));

app.post('/track', (req, res) => {
  const trackData = req.body;
  
  // 1. 数据验证
  if (!Array.isArray(trackData)) {
    return res.status(400).json({ error: 'Invalid data format' });
  }
  
  // 2. 数据处理
  trackData.forEach(item => {
    // 添加服务器时间戳
    item.server_timestamp = Date.now();
    
    // 数据脱敏（示例）
    if (item.event === 'elementClick' && item.textContent) {
      item.textContent = item.textContent.substring(0, 100); // 截断长文本
    }
    
    // 存储到数据库或消息队列
    saveToDatabase(item);
  });
  
  res.status(200).json({ success: true, count: trackData.length });
});

function saveToDatabase(data) {
  // 实现数据存储逻辑
  console.log('Storing data:', data.event, data.uuid);
}

⚠️ 注意事项

1. 隐私合规

• GDPR/CCPA 合规：确保用户同意后再启用监控
• 数据脱敏：避免采集敏感信息（密码、身份证号等）
• 用户告知：在隐私政策中说明数据采集范围

2. 性能影响

• 内存使用：本地缓存可能占用 localStorage 空间
• 网络请求：批量上报可能增加网络负载
• 事件监听：大量事件监听可能影响页面性能

3. 浏览器兼容性

• 现代浏览器：Chrome 60+、Firefox 55+、Safari 11+、Edge 79+
• API 依赖：需要支持 localStorage、fetch、PerformanceObserver
• Polyfill：如需支持旧版浏览器，可能需要添加 polyfill

4. 数据安全

• HTTPS：确保上报地址使用 HTTPS
• 数据加密：敏感数据建议加密后再上报
• 访问控制：后端接口应设置合理的访问控制

🐛 故障排除

常见问题

Q1: 数据没有上报

• 检查网络连接
• 验证上报地址是否正确
• 查看浏览器控制台是否有错误
• 检查 localStorage 是否被禁用

Q2: 性能指标不准确

• 确保在页面加载早期初始化 SDK
• 检查浏览器是否支持 PerformanceObserver API
• 验证页面是否为 SPA（单页应用）

Q3: 点击事件没有文本内容

• 确认点击元素是否为配置的标签类型（button、span、a）
• 检查元素是否有文本内容
• 验证事件监听是否正确绑定

Q4: 路由监控不工作

• 确认是否启用了 observe_router
• 检查是否为 History API 路由
• 验证是否在路由库初始化前调用了 init()

调试模式

// 在开发环境中启用详细日志
if (process.env.NODE_ENV === 'development') {
  // 监听 localStorage 变化查看上报数据
  window.addEventListener('storage', (e) => {
    if (e.key === 'etrackp_data') {
      console.log('Track data:', JSON.parse(e.newValue || '[]'));
    }
  });
}

📄 许可证

MIT License

Copyright (c) 2024 etrackp

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📞 支持与反馈

• 提交 Issue: Gitee Issues
• 文档更新: 欢迎改进本文档
• 功能建议: 通过 Issue 提出新功能建议

版本: 0.0.1
最后更新: 2025-12-24
维护者: etrackp Team