# 下载

```
yarn add zmdms-track --registry https://registry.npmmirror.com
```

# 引入

- es

```
import ZmdmsTrack from  'zmdms-track';
```

- umd

```
<script src="zmdms-track.min.js"></script>
```

# 用法

1. 初始化

   > 在入口处初始化

   ```
   // 初始实例化
   const zmdmsTrackInstance = new ZmdmsTrack({
   	// 初始化传递的基础信息
   	basicInfo: {
   		system: '', // 系统标识
   		appName: '', // 应用名称, app端专用
   		appVersion: '', // 应用版本，app端专用
   		offlineVersion: '', // 离线包版本，app端专用
   		userCode: '', // 用户工号
   		createBy: '', // 用户姓名
   		runtimeInfo: {
   			uuid: '', // 设备码 移动端专属
   			buildVersion: '', // 构建版本 移动端专属
   		}
   	},
   	// 是否开启调试
   	isDebugger: false,
   	// 数据存储key
   	cacheKey: 'cache_key_001',
   	// 全局监听按钮的行为
   	globalClickListeners: [
           {
               selector: "button",
               callback: (data) => {
                 console.log("点击了全局按钮", data);
                 // 某些条件不需要上报
                 if (data.innerText === "儿豁") {
                   return {
                     isTrack: false,
                   };
                 }
               },
           },
   	],
   	// 个性化处理发送请求事件
   	report: {
   		url: '',
   		reportType: 'http',
   		nonHttpMethod: jsBridge,
   	}
   });
   ```

2. 用户自定义事件

   > 用户可以自定义事件，调用实例方法即可

   ```
   // 直接上报数据
   zmdmsTrackInstance.report({
       eventKey: '', // 事件类型 'click' | 'error' 等等，客户端需要整体控制下这个类型，以便后续统计分析
       eventValue: '', // 事件描述
       extra: '', // 扩展信息
   })

   // 存储上报数据 ，等待合适时机上报
   zmdmsTrackInstance.add({
       eventKey: '',
       eventValue: '',
       extra: '',
   })
   ```

3. 可以在适当时机更新基础信息，如果有需要的话

   ```
   // 如果想要更新基础信息
   zmdmsTrackInstance.updateBasicInfo({
   	system: '', // 系统标识
   	appName: '', // 应用名称, app端专用
   	appVersion: '', // 应用版本，app端专用
   	offlineVersion: '', // 离线包版本，app端专用
   	userCode: '', // 用户工号
   	createBy: '', // 用户姓名
   	runtimeInfo: {
   		uuid: '', // 设备码 移动端专属
   		buildVersion: '', // 构建版本 移动端专属
   	}
   })
   ```

# 注意事项

- 开启 debugger

  ```
  new ZmdmsTrack({
  	...,
  	// TODO: 线上环境不要开启debugger，开发环境是否开启 自行选择
  	isDebugger: process.env.NODE_ENV === 'development',
  	...,
  })
  ```

- 如果初始化时，没有一些基础信息（像 uuid）等 可以通过 updateBasicInfo 方法设置

  ```
  instance.updateBasicInfo({
  	...,
  	runtimeInfo: {
  		uuid: '', // 设备码 移动端专属
  		buildVersion: '', // 构建版本 移动端专属
  	}
  	...,
  })
  ```

# 配置参数

## IOptions

| 选项                 | 描述                                                         | 类型                   | 默认                     |
| -------------------- | ------------------------------------------------------------ | ---------------------- | ------------------------ |
| basicInfo            | 初始化时传递的基础信息                                       | IBasicInfo             | 内部自动填充一些信息     |
| pvReport             | 是否开启 PV 统计(在微前端下，子应用应该不需要开启 pv)        | boolean                | true                     |
| countPvType          | 统计 PV 的方式 <br />repeat：每次路由切换都会统计<br />single：不刷新页面统计不会重新计数已经统计过的路由 | `"repeat""single"`     | repeat                   |
| uvReport             | 是否开启UV统计                                               | boolean                | true                     |
| uvMaxTime            | 统计UV的最大时间间隔（uvByDay的优先级高于这个）              | number                 | 24 * 60 * 60 * 1000      |
| uvByDay              | 是否按天统计UV                                               | boolean                | true                     |
| customUvReport       | 自定义统计UV。UV的统计方式完全由系统自定义。如果传入了这个参数，需要完成记录 UV和上报UV的行为。(即判断是否记录UV和调用实例的add方法记录UV都由自己去 实现) | function \| null       |                          |
| getUVKey             | 返回自定义统计UV的key值。主要是在基座下面，需要统计各个系统的UV访问情况，需要通过这个参数来识别当前路由属于哪个系统，并记录一个这个系统的专属UVkey。内部会实现统计UV和上报UV的行为。 | function               |                          |
| isTriggerPathUv      | 路由发生改变时，是否触发UV统计，需要返回一个boolean值。具体是否记录上报UV，具体要看UV的统计规则。默认时按天系统是否被访问。 | function               |                          |
| report               | 上传的接口信息                                               | IReport                | 有默认值，通常不需要处理 |
| errorReport          | 是否开启 报错 上报(默认会统计 error、unhandledrejection 事件) | boolean                | true                     |
| performanceReport    | 是否开启 页面性能 上报(默认会统计`FCP` `FID` `LCP` `CLS` `TTFB`) | boolean                | false                    |
| hashchangeReport     | 是否开启 hash 变化 上报                                      | boolean                | true                     |
| historyReport        | 是否开启 history 变化 上报                                   | boolean                | true                     |
| isDebugger           | 是否开启 debugger                                            | boolean                | false                    |
| historyUrlsNum       | 记录路由最大长度                                             | number                 | 4                        |
| cacheMaxNum          | 缓存上报数据的阈值；超过这个长度后，立即上报                 | number                 | 15                       |
| reportMaxNum         | 每次上报请求最长数据条数                                     | number                 | 20                       |
| cacheKey             | 数据存储 key                                                 | string                 | 确保存储 key 唯一        |
| globalClickListeners | *全局点击监听*                                               | IGlobalClickListener[] |                          |
| dataRewrite          | 插入 数据重写 方法。如果需要对 插入的数据做重写的话，可以传入这个参数。 | (data:IData) =>IData   | (data) => data;          |



## IBasicInfo

| 选项           | 描述                   | 类型               | 默认                        |
| -------------- | ---------------------- | ------------------ | --------------------------- |
| system         | 系统标识               | string \| number   |                             |
| systemName     | 系统标识名称           | string             |                             |
| client         | 客户端标识             | string(web app h5) | 默认会从UA中判断(web还是h5) |
| appName        | 应用名称，app 端专用   | stirng             |                             |
| appVersion     | 应用版本，app 端专用   | stirng             |                             |
| offlineVersion | 离线包版本，app 端专用 | string             |                             |
| userCode       | 用户工号               | string \| number   |                             |
| createBy       | 用户姓名               | string             |                             |
| orgId          | 部门信息               | string             |                             |
| navigator      | 浏览器信息             | string             | 内部会自动获取              |
| runtimeInfo    | 设备相关信息           | IDeviceInfo        | 内部会自动获取一部分        |

## IDeviceInfo

| 选项         | 描述                | 类型   | 默认         |
| ------------ | ------------------- | ------ | ------------ |
| os           | 系统信息            | string | 内部自动获取 |
| device       | 设备信息            | string | 内部自动获取 |
| engine       | 浏览器内核          | stirng | 内部自动获取 |
| browser      | 浏览器信息          | string | 内部自动获取 |
| uuid         | 设备码 移动端专属   | string |              |
| buildVersion | 构建版本 移动端专属 | string |              |



## IReport (自定义上传配置)

| 选项          | 描述                                                         | 类型                         | 默认                                 |
| ------------- | ------------------------------------------------------------ | ---------------------------- | ------------------------------------ |
| url           | 埋点接口地址                                                 | string                       | /api/zmdms-log/event-tracking/submit |
| reportType    | 请求的方式（http会默认调用fetch）                            | http \| beacon               |                                      |
| headers       | 请求头                                                       |                              |                                      |
| format        | 上报数据格式化                                               | (data: IData[]) => IData[]   |                                      |
| customReport  | 请求完全自定义(**外部不要将异常捕获。异常捕获会导致，如果上报接口失败了，内部无法判断是否成功，会直接清空数据**) | (*data*: IData[]) => Promise |                                      |
| isReport      | 自定义决定是否上报                                           | (data: IData[]) => boolean;  |                                      |
| nonHttpMethod | 非http、https场景下的请求方法。当在这些场景下会先取这个方法发送请求。但是这个方法要支持下面这种调用方式。在我们项目中一般指h5的flutter场景。 |                              |                                      |
|               |                                                              |                              |                                      |

```
nonHttpMethod({
	url: url,
    method: "POST",
    headers: {
    	"Content-Type": "application/json",
    	...report.headers,
    },
    body: JSON.stringify({
    	eventTrackings: reportData,
    }),
})
.then((res) => {
	if (res.status !== 200) {
		throw new Error("上报失败");
	}
});
```





## IGlobalClickListener

| 选项         | 描述                                                         | 类型                | 默 认       |
| ------------ | ------------------------------------------------------------ | ------------------- | ----------- |
| selector     | 选择器                                                       | string              |             |
| elementText  | 元素文本                                                     | string              |             |
| **callback** | 交给开发自行处理的时机。<br />根据传递的data信息（包含：targetEl,currentEl,innerText）来判断是否需要执行埋点。如果不需要执行埋点。这个方法应该return { isTrack: false }。需要埋点不需要返回isTrack字段。但是可以返回一些用于统计的数据，如果有需要的话。 | (data: any) => any; | ----------- |
|              |                                                              |                     |             |



# 实例方法

## instance.add (存储到本地，等待合适的时机发送)

```
//
instance.add({
	eventKey: 'click',
	eventValue: '埋点测试',
	extra: JSON.stringify({ message: '用户提交了合同信息' }),
})
```

## instance.report (立即上报)

```
instance.report({
	eventKey: 'click',
	eventValue: '埋点测试',
	extra: JSON.stringify({ message: '用户提交了合同信息' }),
})
```

## instance.updateBasicInfo (修改基础信息)

```
instance.updateBasicInfo({
	system: '', // 系统标识
	appName: '', // 应用名称, app端专用
	appVersion: '', // 应用版本，app端专用
	offlineVersion: '', // 离线包版本，app端专用
	userCode: '', // 用户工号
	createBy: '', // 用户姓名
	runtimeInfo: {
		uuid: '', // 设备码 移动端专属
		buildVersion: '', // 构建版本 移动端专属
	}
})
```

# 项目地址

https://gitlab.zmd.com.cn/zmdms-core/front/zmdms-track



# 其他说明

- 上报接口说明：

  默认接口是：/api/zmdms-log/event-tracking/submit。如果是外部系统需要接入的话，需要配置全路径，要么就做转发到运管这边的服务器。

- 上报缓存的最大 数据长度：

​		默认是15条会上报一次（除非是异常或者主动立即上报的行为）

- 单次上报最大长度：

  默认是20条

- 上报接口失败处理

  失败超过3次后，会5分钟内不进行任何上报