lee_web_track_sdk 0.0.1

package/README.md

@@ -0,0 +1,287 @@
+# Fr24 前端埋点采集 SDK
+
+1. 初始化 sdk
+2. 调用 sdk 对应事件方法
+3. 对应事件拼接由 sdk 处理的参数
+4. 校验数据进行清洗
+5. 清洗完成存入缓存
+6. 判断是否需要聚合数据
+7. 批量上传数据
+
+## ✨ 功能
+
+- ✅ 实现数据采集 & 缓存
+- ✅ 定时上报
+- ✅ 自定义上报
+- ✅ 自定义数据聚合
+- ✅ 自动统计 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. 安装
+
+```bash
+npm install
+# use pnpm
+pnpm install
+# use yarn
+yarn install
+```
+
+### 2. 引入项目
+
+```js
+// main.js
+import FrTrack from 'fr_web_track_sdk/dist/esm';
+
+// or
+
+const FrTrack = require('fr_web_track_sdk');
+```
+
+### 3. 使用
+
+```js
+const frTrack = new FrTrack({
+  // ...options
+});
+
+frTrack.setUser('');
+frTrack.setRouteMode('history');
+```
+
+## 🔧 配置项 Options
+
+```typescript
+interface CustomOptions {
+  project_name: string;
+  report_url: string;
+  app_version?: string;
+  auto_pv?: boolean;
+  maxCacheSize?: number;
+  maxCacheTime?: number;
+}
+```
+
+- `project_name`：**必选**，项目名称
+- `report_url`：**必选**，上报地址
+- `app_version`：**非必选**，项目版本，默认 unknown
+- `auto_pv`：**非必选**，是否自动捕获 pv，默认 false
+- `maxCacheSize`：**非必选**，最大缓存事件阈值，达到阈值自动上报，默认 15
+- `maxCacheTime`：**非必选**，最大缓存时间阈值，达到阈值自动上报，默认 300000 毫秒（5 分钟）
+
+## 🔧 实例方法
+
+创建 SDK 实例后，实例提供不同的实例方法，方法名称、功能及传参如下
+
+- `setUser`：设置用户 id，用于统计 UV 及区分用户
+
+  | 参数 | 类型   | 默认值 |
+  | ---- | ------ | ------ |
+  | id   | string | 空     |
+
+```js
+frTrack.setUser('123');
+```
+
+- `setRouteMode`：设置路由方式，用于自动统计 PV
+
+  | 参数 | 类型            | 默认值  |
+  | ---- | --------------- | ------- |
+  | mode | history \| hash | history |
+
+```js
+frTrack.setRouteMode('hash');
+```
+
+- `frModuleView`：模块漏出事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frModuleView('moduleAView', {
+  pid: 1
+  // other
+});
+```
+
+- `frModuleClick`：模块点击事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frModuleClick('moduleAClick', {
+  pid: 1
+  // other
+});
+```
+
+- `frLoginEvent`：登录事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frLoginEvent('b2bLogin', {
+  username: '123',
+  loginStatus: 'success'
+  // other
+});
+```
+
+- `frOrderEvent`：生单事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frOrderEvent('b2bOrder', {
+  username: '123',
+  orderNo: '******'
+  orderStatus: 'success'
+  // other
+});
+```
+
+- `frCustomEvent`：自定义事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frCustomEvent('mouseUp', {
+  // other
+});
+```
+
+- `frLogEvent`：日志事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frLogEvent('getCarrierListLog', {
+  logType: 'error',
+  logInfo: '******'
+  // other
+});
+```
+
+- `frClickEvent`：点击事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frClickEvent('searchClick', {
+  searchContent: '******'
+  // other
+});
+```
+
+- `frPageView`：PV 事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frPageView('searchPageView', {
+  pageUrl: '******'
+  // other
+});
+```
+
+- `frUserView`：UV 事件（需提前调用 setUser）
+
+  | 参数 | 类型 | 默认值 |
+  | ---- | ---- | ------ |
+  | 无   | 无   | 无     |
+
+```js
+frTrack.frUserView();
+```
+
+- `frPageDestroy`：页面销毁事件
+
+  | 参数        | 类型   | 默认值 |
+  | ----------- | ------ | ------ |
+  | event_name  | string | 必传   |
+  | custom_data | object | 空     |
+
+```js
+frTrack.frPageDestroy('searchPageDestroy', {
+  inTime: '',
+  leaveTime: ''
+  // other
+});
+```
+
+- `frReport`：立即上报（调用后可立即将本次及之前的埋点数据进行上报）
+
+  | 参数 | 类型 | 默认值 |
+  | ---- | ---- | ------ |
+  | 无   | 无   | 无     |
+
+```js
+frTrack.frReport();
+```
+
+## 💡 数据聚合
+
+SDK 中自动将`page_view`, `user_view`, `module_view`三类事件上报时进行了聚合处理 _（多次上报仅记录一次）_
+
+如果想针对其他时间进行聚合处理，如搜索内容的上报，可在参数中添加`is_aggregation`字段，该字段为`boolean`类型，在上报时会根据该字段的值，对同类型的事件进行聚合处理。
+
+> 事件类型相同 & 事件名称相同的事件会被视为`同类型事件`
+
+```js
+// 该事件会被自动聚合
+frTrack.frClickEvent(
+  'searchClick',
+  {
+    searchContent: '******'
+  },
+  true
+);
+```