Fr24 前端埋点采集 SDK

✨ 功能

• ✅ 实现数据采集 & 缓存
• ✅ 定时上报
• ✅ 自定义上报
• ✅ 自定义数据聚合
• ✅ 自动统计 UV 数据
• ✅ 支持自动统计 PV 数据

🎯 项目简介

该项目为针对FR24 前端组项目的一款全链路埋点采集、上报 SDK，支持在以下环境使用：

• 原生 JavaScript 开发且运行于浏览器环境下的项目
• Vue、React（暂未支持） 等前端框架开发且运行于浏览器环境下的项目

🚀 支持事件

该 SDK 仅支持以下埋点事件

• page_view：用于统计页面访问数据；
• user_view：用于访问页面访问用户数据；
• page_destroy：用于记录页面销毁事件，记录用户访问时间及离开时间；
• click_event：用于统计点击触发的埋点事件；
• module_view：用于统计模块状态的埋点事件（如某块区域的展示隐藏）；
• module_click：用于统计模块点击的埋点事件（如某块区域的点击）；
• login_event：用于统计登录事件的埋点；
• order_event：用于统计生单事件的埋点；
• custom_event：自定义种类的埋点事件；
• log_event：日志类型的埋点事件；

📦 使用方式

1. 安装

npm install
# use pnpm
pnpm install
# use yarn
yarn install

2. 引入项目

// main.js
import FrSDK from 'fr-web-monitor-sdk';

3. 使用

const webSDK = FrSDK.init({
  // ...options
});

webSDK.setUser('');

export const frTrack = webSDK.$track;

🔧 配置项 Options

interface Options {
  project_name: string;
  report_url: string;
  app_version: string;
  adapter: 'web' | 'miniProgram';
  maxCacheSize: number;
  maxCacheTime: number;
  maxTimeout: number;
  plugins: {
    type: 'track' | 'error' | 'performance';
    options: Record<string, unknown>;
  }[];
}

• project_name：必选，项目名称
• report_url：必选，上报地址
• app_version：非必选，项目版本，默认 unknown
• adapter：非必选，运行环境，默认 web
• maxCacheSize：非必选，最大缓存事件阈值，达到阈值自动上报，默认 15
• maxCacheTime：非必选，最大缓存时间阈值，达到阈值自动上报，默认 300000 毫秒（5 分钟）
• maxTimeout：非必选，最大上报超时时间阈值，达到阈值中止上报，默认 30000 毫秒（30 秒）

🔧 实例方法

创建 SDK 实例后，实例提供不同的实例方法，方法名称、功能及传参如下

• setUser：设置用户 id，用于统计 UV 及区分用户

  | 参数 | 类型 | 默认值 | | ---- | ------ | ------ | | id | string | 空 |

frTrack.setUser('123');

• setRouteMode：设置路由方式，用于自动统计 PV

  | 参数 | 类型 | 默认值 | | ---- | --------------- | ------- | | mode | history | hash | history |

frTrack.setRouteMode('hash');

• frModuleView：模块漏出事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frModuleView('moduleAView', {
  pid: 1
  // other
});

• frModuleClick：模块点击事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frModuleClick('moduleAClick', {
  pid: 1
  // other
});

• frLoginEvent：登录事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frLoginEvent('b2bLogin', {
  username: '123',
  loginStatus: 'success'
  // other
});

• frOrderEvent：生单事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frOrderEvent('b2bOrder', {
  username: '123',
  orderNo: '******'
  orderStatus: 'success'
  // other
});

• frCustomEvent：自定义事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frCustomEvent('mouseUp', {
  // other
});

• frLogEvent：日志事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frLogEvent('getCarrierListLog', {
  logType: 'error',
  logInfo: '******'
  // other
});

• frClickEvent：点击事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frClickEvent('searchClick', {
  searchContent: '******'
  // other
});

• frPageView：PV 事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frPageView('searchPageView', {
  pageUrl: '******'
  // other
});

• frUserView：UV 事件（需提前调用 setUser）

  | 参数 | 类型 | 默认值 | | ---- | ---- | ------ | | 无 | 无 | 无 |

frTrack.frUserView();

• frPageDestroy：页面销毁事件

  | 参数 | 类型 | 默认值 | | ----------- | ------ | ------ | | event_name | string | 必传 | | custom_data | object | 空 |

frTrack.frPageDestroy('searchPageDestroy', {
  inTime: '',
  leaveTime: ''
  // other
});

• frReport：立即上报（调用后可立即将本次及之前的埋点数据进行上报）

  | 参数 | 类型 | 默认值 | | ---- | ---- | ------ | | 无 | 无 | 无 |

frTrack.frReport();

💡 数据聚合

SDK 中自动将page_view, user_view, module_view三类事件上报时进行了聚合处理 （多次上报仅记录一次）

如果想针对其他时间进行聚合处理，如搜索内容的上报，可在参数中添加is_aggregation字段，该字段为boolean类型，在上报时会根据该字段的值，对同类型的事件进行聚合处理。

事件类型相同 & 事件名称相同的事件会被视为同类型事件

// 该事件会被自动聚合
frTrack.frClickEvent(
  'searchClick',
  {
    searchContent: '******'
  },
  true
);