# @doctorwork/web-report-sdk

> web monitor sdk

Latest version **1.13.3** (published 2022-12-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install @doctorwork/web-report-sdk
pnpm add @doctorwork/web-report-sdk
yarn add @doctorwork/web-report-sdk
bun add @doctorwork/web-report-sdk
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.13.3 |
| Published | 2022-12-29 |
| First published | 2019-12-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 64.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mayiwen |
| Maintainers | dw-luojie, newset, lansezhaji, zimv, miaotang, simboltj, critas, cundh, cangku |

## Links

- npm: https://www.npmjs.com/package/@doctorwork/web-report-sdk
- npm.io page: https://npm.io/package/@doctorwork/web-report-sdk

## Dependencies (1)

- [@testing-library/react](https://npm.io/package/@testing-library/react.md) ^10.4.9

## Recent versions

- 1.13.3 (latest) — 2022-12-29
- 1.13.1-alpha.0 (beta) — 2021-09-13
- 1.13.2 — 2022-12-27
- 1.13.1 — 2021-09-15
- 1.13.0-alpha.0 — 2021-09-01
- 1.12.1 — 2021-08-27
- 1.12.0 — 2021-08-24
- 1.12.0-alpha.2 — 2021-08-23
- 1.12.0-alpha.1 — 2021-08-23
- 1.12.0-alpha.0 — 2021-08-23
- 1.11.1 — 2021-07-15
- 1.10.5 — 2021-07-14
- 1.11.0 — 2021-07-14
- 1.7.1 — 2021-07-14
- 1.10.4 — 2021-06-08
- … 34 more at https://npm.io/package/@doctorwork/web-report-sdk/versions

## README

### 引入方式

```js
npm install @doctorwork/web-report-sdk --save
```

```js

import webReportSdk from '@doctorwork/web-report-sdk';
const monitor = webReportSdk({
    appId: "xxx",
    env: "dev",
    filterUrls: ['api/xxxx/xx'],
    errcodeReport(res) {
      if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
        return { isReport: true, errMsg: res.errmsg,code: res.errcode };
      }
      return { isReport: false };
    },
    isTraceId: true,
    traceIdHeaderName: 'x-trace-id';
})
```

### 参数说明

| 初始化参数 | 类型| 是否必填 | 默认 |  用例 | 描述 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| appId | String | 必填 | 无 | - | 小程序的appId |
| env | String | 可选 |无 | prod \| production , qa , dev , pre | 控制domain地址：prod和production都为线上，不同环境内部会走不同接口 |
| domain | String | 可选 | 默认线上环境地址 | https://api-dev.doctorwork.com/web-monitor/api/v1/wx/report/wx | 定义上报api地址，优先级高于env （推荐使用env）|
| filterUrls | Array | 可选 | 无 | ['api/xx'] | 可以过滤部分接口不对其做上报，比如一些轮训，字符串模糊匹配（尽量保证路径完整，模糊匹配可能会影响到其他接口）|
| errcodeReport(业务接口异常上报)  | Function | 可选 | 无 | 例子见下方 | 请求接口，httpstatus为200，业务接口异常通过消息体返回的错误。比如errcode为1代表后端代码异常，此时我们需要上传异常给监控 |
| isTraceId  | boolean | 可选 | false | 无 | 是否开启traceId获取 |
| traceIdHeaderName(服务端响应头返回的traceId字段名)  | string | 可选 | x-qexr-trace-id | 无 | 响应头需要2个字段 access-control-expose-headers: x-qexr-trace-id （允许前端获取）；x-qexr-trace-id:bdDq1a.a123.12 |

#### sdk默认会过滤的接口域名
- 'hm.baidu.com' //百度统计
- 'ssdata.xrxr.xyz' //神策
- 'sentry.aihaisi.com/' //sentry

三方统计的请求会造成大量垃圾数据，目前监控不会收集此类接口的数据，如果业务需要过滤部分不需要监控的接口，使用 filterUrls 。

#### 使用域名判断env
```
import webReportSdk, { utils } from '@doctorwork/web-report-sdk';
const monitor = webReportSdk({
    appId: "xxx",
    env: utils.getEnvByDomain(),
})
```

目前支持的域名枚举
```
const orgins = [
  {
    domain: 'xingrengo.com',
    env: 'dev',
  },
  {
    domain: 'web-dev.doctorwork.com',
    env: 'dev',
  },
  {
    domain: 'web-qa.doctorwork.com',
    env: 'qa',
  },
  {
    domain: 'aihaisi.com',
    env: 'qa',
  },
  {
    domain: 'xingrenys.com',
    env: 'pre',
  },
  {
    domain: 'web-pre.doctorwork.com',
    env: 'pre',
  },
  {
    domain: 'webprod.doctorwork.com',
    env: 'prod',
  },
  {
    domain: 'xrxr.xyz',
    env: 'prod',
  },
  {
    domain: 'xingren.com',
    env: 'prod',
  },
];
```

### errcodeReport:
```
  webReportSdk({
    errcodeReport(res) {
      if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
        return { isReport: true, errMsg: res.errmsg,code: res.errcode };
      }
      return { isReport: false };
    }
  });
```
##### 注意正向和反向判断
我们可能通过fetch或者xmlHttpRequest去请求任何资源比如接口、css、js(也可能是框架发送的请求)，errcodeReport接收的res响应数据，可能是字符串或者对象等多种类型，我们可能需要更加严格的判断来正确的判断是否需要上报业务错误，
比如

##### 正向判断res.errcode===1
```
errcodeReport(res) {
  if (Object.prototype.toString.call(res) === '[object Object]' && res.errcode == 1) {
    return { isReport: true, errMsg: res.errmsg,code: res.errcode };
  }
  return { isReport: false };
}

```
##### 反向判断res.errcode!==0，如果不使用hasOwnProperty，那不存在errcode属性的接口响应也会被当作错误上报（我们的业务接口有些并不一定是完全规范的）
```
errcodeReport(res) {
  if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
    return { isReport: true, errMsg: res.errmsg,code: res.errcode };
  }
  return { isReport: false };
}

```

 
## 方法
### setConfig：设置用户信息
可以只设置任意一个属性

```js
monitor.setConfig({
  p: '1510123131',//电话
  uid: '100017' //用户id
});
```


### addError：手动上报错误信息

```js
let message = 'js add error';
let col = 20;
let line = 20;
let resourceUrl = 'http://www.xxx.com/01.js';

monitor.addError({
  msg: message,
  col: col,
  line: line,
  resourceUrl: resourceUrl
});
```

### addCustom: 自定义埋点

```
const monitor = webReportSdk({
    appId: "xxx",
    env: 'dev'
})
//默认立刻执行，如果不需要立刻执行，可以设置reportNow为false，埋点会进队列而后其他地方执行report或者页面切换或者其他接口请求，上报的时候会带上customs队列。
//reportNow默认true，可选参数
monitor.addCustom({
    customName: 'mgStart-getUserInfo',
    customContent: {
      userId: 123,
      system: {
        version: '1.2'
      }
    },
    /*
      非必填字段，自定义筛选条件，必须为对象，否则无效，手动选择部分字段上传。
      监控后台通过增删改filter字段，来筛选自定义的参数。也就是说当前customContent里的内容如果需要后期查询做筛选，需要把字段传入
      注意：customFilter只支持1层对象
    */
    customFilter: {
      userId: 123,
      version: '1.2'
    }
}, reportNow);
```

#### 浏览器页面直接引用资源方式(不推荐)：

> - 1、下载 dist/web-report-default.min.js 到本地
> - 2、使用 script 标签引入到 html 的头部（备注：放到所有 js 资源之前）
> - 3、调用初始化方法

```html
<html>
  <head>
    <meta charset="UTF-8" />
    <script src="../dist/default.min.js" crossorigin></script>
    <script>
      dta.init({
        env: 'qa',
        appId: 'xxxx',
      });
    </script>
  </head>
</html>
```

## 跨域获取不到错误信息问题
当我们引入跨域的script资源并且此script内部有js报错的时候，sdk全局window.onerror将无法捕获到详细报错，只会获取到一个msg：Script error.
解决的方法就是给跨域的script标签使用crossorigin属性，并且需要服务器为当前资源设置cors

### SDK 主要上报以下性能信息

> - url 上报页面地址
> - preUrl 来访上一页面 URL
> - performance 页面性能数据详情，字段含义详情请参考后面内容
> - errorList 页面错误信息详情，包含 js,img,ajax,fetch 等所有错误信息，字段含义详情请参考后面内容
> - resoruceList 页面性能数据详情，当前页面所有资源性能详情信息，字段含义详情请参考后面内容
> - markUv 统计 uv 标识
> - markUser 从用户进入网站开始标识，直到用户离开销毁，可以用来做用户漏斗分析
> - time 当前上报时间
> - screenwidth 屏幕宽度
> - screenheight 屏幕高度
> - isFristIn 是否是某次会话的第一次进入
> - type 上报类型 1:页面级性能上报 2:页面 ajax 性能上报 3：页面内错误信息上报

---
_Source: https://npm.io/package/@doctorwork/web-report-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._