埋点系统文档（第一版：PC与H5端）

一、事件类型

1. 点击事件 (click)

记录用户的点击行为，包括自定义埋点元素和普通元素的点击。

{
  eventType: 'click',
  elementType: string,     // 元素类型
  pageUrl: string,        // 页面URL
  timestamp: number,     // 事件发生时间戳
  targetInfo: {           // 点击元素信息
    tagName: string,      // 标签名
    className: string,    // 类名
    id: string,          // 元素ID
    textContent: string  // dom节点内容（文本内容，a标签、img标签的alt || title）
  },
  trackParams?: object,   // 自定义埋点参数
  device_info: {...}      // 设备信息
}

2. 页面访问事件 (pageView)

记录页面路由切换。

{
  eventType: 'pageView',
  timestamp: number,
  fromPath: string,      // 来源路径
  toPath: string,       // 目标路径
  device_info: {...}
}

3. 元素曝光事件 (exposure)

记录元素的可见性和停留时长。

{
  eventType: 'exposure',
  timestamp: number,
  elementType: string,   // 元素类型
  trackId: string,      // 埋点ID
  duration: number,     // 曝光时长(ms)
  pageUrl: string,     // 页面URL
  device_info: {...},
  ...trackParams       // 自定义参数
}

4. 页面加载 (pageLoad)

记录页面的生命周期。

{
  eventType: 'pageLoad',
  pageUrl: string,      // 页面URL
  timestamp: number,
  pageTitle: string,    // 页面标题
  loadTime: number,     // 加载耗时(ms)
  device_info: {...}
}

5. 页面刷新/离开事件 (pageRefresh)

记录页面的生命周期。

{
  eventType: 'pageRefresh',
  timestamp: number,
  pageUrl: string,      // 页面URL
  pageTitle: string,    // 页面标题
  duration: number,     // 停留时长(ms)
  device_info: {...}
}

二、公共字段

所有事件都包含以下字段：

1. 基础信息

• eventType: 事件类型
• pageUrl: 当前页面URL
• timestamp: 事件发生时间戳
• globalId: 构建完整用户行为链路的关键基础埋点。

2. 设备信息 (deviceInfo)

{
  userAgent: string,     // 设备信息
  screenWidth: number,   // 屏幕宽度
  screenHeight: number,  // 屏幕高度
  language: string       // 语言设置
}

三、使用示例

全局引入

全局生效埋点提交，不需要配置到具体触发元素上，支持click、pageView、pageRefresh事件

// package.json添加依赖
"dependencies": {
  "FrontSightSDK": "git+http://dev.jinliwangluo.com:8021/frontend/FrontSightSDK.git#master"
}
// 在项目入口处引入埋点脚本：
import frontSightSDK from 'FrontSightSDK'
const autoTracking = frontSightSDK.useWebAutoTracking(router, apiMethod)  // 传入router实例和上传接口方法 
// 在应用启动时初始化埋点系统
autoTracking.init()
// 在应用销毁时清理埋点系统
autoTracking.destroy()

具体项目示例（mobile-v3）

// 在src/plugins下新建tracking.clien.js
// tracking.client.js
import Request from '@/api/clientApi/request'
import frontSightSDK from 'FrontSightSDK'

export default defineNuxtPlugin(nuxtApp => {
	const router = useRouter()
	const trackRecord = (data, options) => {
		return new Request().post(`/dashboard/monitor/public/common/count/hit`, data, options)
	}
	const autoTracking = frontSightSDK.useWebAutoTracking(router, trackRecord)

	// 在应用启动时初始化埋点系统
	nuxtApp.hook('app:mounted', async () => {
		try {
			autoTracking.init()
		}
		catch (e) {
			console.error('AutoTracking init failed:', e)
		}
	})

	// 在应用销毁时清理埋点系统
	nuxtApp.hook('app:beforeDestroy', () => {
		autoTracking.destroy()
	})
})

特定埋点

1. 单独添加点击事件埋点(针对性统计信息)

<button 
  data-track-click='{"action":"submit","category":"form"}'
>
  提交
</button>

<!-- 若在模板语法中使用，需转换成JSON字符串，如下 -->
 <button 
  v-for="item in xxx"
	:data-track-click="JSON.stringify({ eventName: item.text })"
>
  我要出售
</button>

// 使用服务式方式调用van-dialog 无法获取元素 给按钮添加埋点的方式如下：添加cancel-button-click/confirm-button-click属性
showConfirmDialog({
    'title': '确定要取消订单吗？',
    'showCancelButton': true,
    'message': '订单取消后无法恢复, 是否确认取消订单？',
    'confirmButtonText': '确定取消',
    'cancelButtonText': '我再想想',
    'cancel-button-click': JSON.stringify({ eventName: '我再想想', goodsNo: orderDetail.goodsNo, orderNo: orderDetail.orderNo }),
    'confirm-button-click': JSON.stringify({ eventName: '我再想想', goodsNo: orderDetail.goodsNo, orderNo: orderDetail.orderNo })
})

2. 添加曝光埋点(针对性统计信息)

<!-- 目前存在的三种曝光类型 -->
const EXPOSURE_TYPE = {
    IMMEDIATE: "immediate",  // 默认值
    BATCH:  "batch",
    DURATION: "duration"
}
<!-- 立即曝光埋点 -->
<div 
  :data-track-exposure='JSON.stringify({ eventName: item.text })'
>
  广告内容
</div>
<!-- 批量立即曝光埋点（每六个上报一次）, param参数值将push进入数组中合并上报 -->
<div 
  :data-track-exposure="JSON.stringify({ _type: 'batch', module_id: 'home_list', param: item.text })"
>
  广告内容
</div>
<!-- 元素曝光时间埋点 -->
<div 
  :data-track-exposure="JSON.stringify({ _type: 'duration', eventName: item.text })"
>
  广告内容
</div>

四、其他

1. 批量处理：每次最多6条数据同时上报
2. 防抖处理：500ms延迟上报
3. 点击去重：300ms内重复点击只记录一次
4. 自动采集：支持自动采集未标记埋点的有效点击