# 前端监控及埋点 SDK 工具

## 使用

```shell
# using npm
$ npm install monitor-track -S

```

```typescript
import Track from 'monitor-track';

const track = new Track();

track.init({
  projectID: 'IuggBOP==',   // 由监控平台后台管理系统创建项目时生成
  reportUrl: 'https://api-track.zhoushoujian.com/monitor-service/s/r', //上报地址
  spa: true,
  hash: true, // 不是hash模式的项目一定要改成false，否则不能统计到pv的类型
  enable: true,
  customPayload,
  ignore: {
    errors: [
      'ResizeObserver loop limit exceeded',
      'ResizeObserver loop completed with undelivered notifications.',
    ],
  },

});

// 注意：sdk默认取localStorage.getItem('username')作为uuid，所以如果要将用户名作为用户标识，请将username存到localStorage中
// 如果localStorage.getItem('username')取不到值，则会使用uuid作为用户标识，这时用户标识是匿名的，有可能会出现一个用户统计为两个或多个用户的情况
```

## 配置项

| 配置项                | 类型          | 必填 | 默认值 | 注释                                               |
| --------------------- | ------------- | ---- | ------ | -------------------------------------------------- |
| reportUrl             | string        | 是   | ''     | 上报地址，后台地址                                 |
| projectID             | string        | 是   | ''     | 项目 ID                                            |
| spa                   | boolean       | 否   | false  | 是否为单页面应用，主要区别页面性能，及路由切换行为 |
| hash                  | boolean       | 否   | false  | 路由是否为 hash 模式                               |
| enableBehavior        | boolean       | 否   | true   | 启用用户行为上报                                   |
| enableError           | boolean       | 否   | true   | 启用异常信息上报                                   |
| enableErrorScreenshot | boolean       | 否   | false  | 启用异常时的截图上报                                   |
| enableErrorEvent      | boolean       | 否   | false  | 启用异常时的录像上报                                   |
| enableVisualTrack     | boolean       | 否   | false  | 启用可视化埋点上报                                 |
| enableLagTrack        | boolean       | 否   | false  | 启用页面卡顿信息上报                                   |
| lagTimeout            | number        | 否   | 400    | 页面卡顿上报的阈值时间（毫秒）                             |
| enableRecord          | boolean       | 否   | false  | 启用页面录制                                       |
| enableOnlinePersons   | boolean       | 否   | true   | 显示在线人数                                       |
| ignore                | 见下方 ignore  | 否   | false  | 忽略上报的信息                                     |
| customPayload         | string        | 否   | false  | 自定义 payload                                     |
| enable                | boolean       | 否   | false  | 是否开启日志收集，默认关闭                         |
| maxLength             | number        | 否   | 1000   | 最长上报数据长度                                   |
| XMLHttpRequestTimeout | number        | 否   | 1000   | 上报 xhr 请求超过指定时间                          |

### ignore

| 参数   | 类型     | 必填 | 默认值 | 注释           |
| ------ | -------- | ---- | ------ | -------------- |
| urls   | string[] | 否   | []     | 忽略的 url     |
| errors | string[] | 否   | []     | 忽略的异常信息 |
| apis   | string[] | 否   | []     | 忽略的接口     |

## 全局方法

```typescript
//注意：以下window上的方法，如果没有enable埋点，那么这些window上的方法都不存在

//手动上报视频录像, 视频时间应当在30秒到60秒之间
if (typeof window.getRRWebUserEventsCaptureFunc ！== 'undefined') {
  window.getRRWebUserEventsCaptureFunc()
} else {
  //console.log('getRRWebUserEventsCaptureFunc is undefined, check monitor-track version!)
}

//手动截图, 图片内容包含整个页面内容，注意getFullScreenShootFunc返回一个Promise
if (typeof window.getFullScreenShootFunc ！== 'undefined') {
  window.getFullScreenShootFunc().catch((err) => { console.error('截图失败', err) })
} else {
  //console.log('getFullScreenShootFunc is undefined, check monitor-track version!)
}

//手动上报,data必须是一个对象
if (typeof window.manualReportTrackFunc ！== 'undefined') {
  window.manualReportTrackFunc(data)
} else {
  //console.log('manualReportTrackFunc is undefined, check monitor-track version!)
}
```

## 项目引入时，定义环境变量，防止开发环境中上报信息

```javascript
// webpack中配置环境变量

new webpack.DefinePlugin({
  isDev: 'development',
});
```

```typescript
const isDevEnv = typeof isDev !== 'undefined';

if (isDevEnv) {
  track.init({
    // 由监控平台后台管理系统创建项目时生成
    projectID: '123',
    reportUrl: 'http://localhost:3008/report',
    spa: true,
    // 不是hash模式的项目一定要改成false，否则不能统计到pv的类型
    hash: true,
  });
}
```