shen-tool-frontend-track

前端埋点SDK - 支持页面曝光、元素曝光、元素点击

安装

npm install shen-tool-frontend-track

使用

初始化

import { Analytics } from 'shen-tool-frontend-track';

// 创建实例
const analytics = new Analytics({
  endpoint: '/api/analytics',
  appId: 'shen-tool'
});

页面曝光

自动追踪，无需手动调用。页面加载或路由变化时会自动上报。

元素曝光

在需要追踪的元素上添加 data-track 属性：

<div data-track="Banner图">
  ...
</div>

当元素进入视口时自动上报。

元素点击

手动调用 trackClick 方法：

<Button onClick={() => analytics.trackClick('登录按钮')}>
  登录
</Button>

配置选项

interface AnalyticsOptions {
  /** 上报地址 (必填) */
  endpoint: string;
  /** 应用ID (必填) */
  appId: string;
  /** 队列阈值，默认20 */
  maxQueueSize?: number;
  /** 上报间隔，默认5000ms */
  flushInterval?: number;
  /** 是否自动追踪页面曝光，默认true */
  autoTrackPageView?: boolean;
  /** 是否自动追踪元素曝光，默认true */
  autoTrackElementView?: boolean;
  /** 是否自动追踪元素点击，默认true */
  autoTrackElementClick?: boolean;
  /** 获取用户ID的函数 */
  getUserId?: () => string;
}

数据结构

页面曝光

{
  "eventType": "page_view",
  "pageName": "工具页面",
  "pageUrl": "/tools",
  "referrer": "/home",
  "stayDuration": 30000,
  "userId": "user_xxx",
  "appId": "shen-tool",
  "timestamp": 1700000000000
}

元素曝光

{
  "eventType": "element_view",
  "pageName": "首页",
  "pageUrl": "/home",
  "elementName": "Banner图",
  "userId": "user_xxx",
  "appId": "shen-tool",
  "timestamp": 1700000000000
}

元素点击

{
  "eventType": "element_click",
  "pageName": "首页",
  "pageUrl": "/home",
  "elementName": "登录按钮",
  "userId": "user_xxx",
  "appId": "shen-tool",
  "timestamp": 1700000000000
}

上报机制

• 批量上报：达到20条立即上报
• 定时上报：每5秒上报一次
• 页面隐藏时立即上报
• 使用 sendBeacon 确保页面卸载时也能上报