aegis-mp-sdk 1.36.3 → 1.36.5

package/README.md

@@ -1,6 +1,6 @@
 # aegis-mp-sdk
 
-Aegis（读音/ˈiːdʒɪs/） 是腾讯云监控团队提供的前端监控 SDK，涵盖了错误监控，资源测速（img, script, css），接口测速，页面性能（首屏时间）。无需侵入代码，只需引入 SDK 即可自动完成所有监控上报。
+Aegis 是腾讯云监控团队提供的前端监控 SDK，涵盖了错误监控，资源测速（img, script, css），接口测速，页面性能（首屏时间）。无需侵入代码，只需引入 SDK 即可自动完成所有监控上报。
 
 在使用 aegis 时无需在业务代码中打点或者做任何其他操作，可以做到与业务代码充分解耦。aegis 将会自动监控前端错误，在错误发生时上报错误的具体情况，帮助您快速定位问题。当您开启资源测速时，aegis 将会自动监听页面资源加载情况（耗费时长、成功率等），并在不影响前端性能的前提下收集前端的性能数据，帮助您快速定位性能短板，提升用户体验。
 
@@ -10,6 +10,14 @@ aegis-mp-sdk 是针对微信小程序和QQ小程序开发的数据收集和上
 
 ## 使用
 
+### 安装
+
+在项目支持 NPM 时推荐使用 NPM 安装 Aegis SDK。
+
+```bash
+$ npm install --save aegis-mp-sdk
+```
+
 ### 初始化
 
 使用非常简单，只需要新建一个 Aegis 实例，传入相应的配置即可：
@@ -18,14 +26,30 @@ aegis-mp-sdk 是针对微信小程序和QQ小程序开发的数据收集和上
 import Aegis from 'aegis-mp-sdk';
 
 const aegis = new Aegis({
-    id: "pGUVFTCZyewxxxxx", // 项目key
+    id: "pGUVFTCZyewxxxxx", // 项目上报ID
     uin: 'xxx', // 用户唯一 ID（可选）
-    reportApiSpeed: true // 接口测速
+    reportApiSpeed: true, // 接口测速
+    reportAssetSpeed: true, // 静态资源测速
+    spa: true, // spa 页面需要开启，页面切换的时候上报pv
 })
 ```
 
+如果使用 ES 模块的方式引入 Aegis 后报错，可以通过如下方式解决
+
+
+方法一：在 tsconfig.json 中设置 `esModuleInterop:true`，然后再通过 `import Aegis from 'aegis-mp-sdk'` 引入
+
+方法二：`import * as Aegis  from 'aegis-mp-sdk'`
+
+方法三：`const Aegis = require('aegis-mp-sdk')`
+
+
 ::: warning 注意 ⚠️
 为了不遗漏数据，须尽早进行初始化；
+
+aegis-sdk 默认使用 `https://aegis.qq.com` 作为上报域名，您也可以选择使用 `https://rumt-zh.com` 作为上报域名。
+
+小程序接入，正式环境需要将上报域名添加到安全域名中。
 :::
 
 ::: tip 当您做了以上接入工作之后，您已经开始享受 Aegis 提供的以下功能：
@@ -34,85 +58,138 @@ const aegis = new Aegis({
 3、数据统计和分析：可在 [RUM 平台](https://console.cloud.tencent.com/rum) 上查看各个纬度的数据分析；
 :::
 
-### 日志上报
+## 日志
 
-创建完 Aegis 实例之后，就可以开心的上报日志啦 🥰，日志上报同样简单
+Aegis SDK 会主动收集用户的一些性能和错误日志，开发者可以根据不同的参数来配置哪些日志需要上报，以及上报的日志具体信息。
 
-```javascript
-aegis.info(
-  `我是一条白名单上报的信息，只有在白名单中的用户才会上报哟。`
-);
+### 日志类型
 
-aegis.infoAll(
-  `我是一条普通的信息，如果上报量很大的话请谨慎使用哟。`
-);
+全部日志类型如下：
 
-aegis.report(
-  new Error('我是一条错误信息，推荐在try..catch或者Promise.reject中使用。')
-)
+```javascript
+{ logType: 'custom', name: '自定义测速' }
+{ logType: 'event', name: '自定义事件' }
+{ logType: 'log', name: '日志' }
+{ logType: 'performance', name: '页面测速' }
+{ logType: 'pv', name: '页面PV' }
+{ logType: 'speed', name: '接口和静态资源测速' }
+{ logType: 'vitals', name: 'web vitals' }
 ```
 
-## aid
 
-Aegis SDK 为每个用户设备分配的唯一标示，会存储在小程序的 storage 里面，用来区分用户，计算 uv 等。aid 只有用户清理小程序缓存才会更新。
+### 日志等级
 
-算法如下:
+全部日志等级如下：
 
 ```javascript
-import { Plugin } from 'aegis-core';
-
-export default new Plugin({
-  name: 'aid',
-  aid: '',
-  init() {
-    const env = wx || qq;
-    // 某些情况下操作 localStorage 会报错.
-    try {
-      let aid = env.getStorageSync('AEGIS_ID');
-      if (!aid) {
-        aid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-          const r = (Math.random() * 16) | 0;
-          const v = c === 'x' ? r : (r & 0x3) | 0x8;
-          return v.toString(16);
-        });
-        env.setStorageSync('AEGIS_ID', aid);
-      }
-      this.aid = aid;
-    } catch (e) {}
-  },
-  onNewAegis(aegis) {
-    aegis.bean.aid = this.aid;
-  },
+  { level: 1, name: '白名单日志' },
+  { level: 2, name: '一般日志' },
+  { level: 4, name: '错误日志' },
+  { level: 8, name: 'Promise 错误' },
+  { level: 16, name: 'Ajax 请求异常' },
+  { level: 32, name: 'JS 加载异常' },
+  { level: 64, name: '图片加载异常' },
+  { level: 128, name: 'css 加载异常' },
+  { level: 256, name: 'console.error' },
+  { level: 512, name: '音视频资源异常' }
+  { level: 1024, name: 'retcode 异常' }
+  { level: 2048, name: 'aegis report' }
+  { level: 4096, name: 'PV' }
+  { level: 8192, name: '自定义事件' }
+  { level: 16384, name: '小程序 页面不存在' }
+  { level: 32768, name: 'websocket错误' }
+  { level: 65536, name: 'js bridge错误' }
+```
+
+### 日志上报
+
+创建完 Aegis 实例之后，就可以开心的上报日志啦 🥰，日志上报同样简单。
+
+```javascript
+// info 可以上报任意字符串，数字，数组，对象，但是只有打开页面的用户在名单中才会上报
+aegis.info('test');
+aegis.info('test', 123, ['a', 'b', 'c', 1], {a: '123'});
+
+
+// 也可以上报特定的对象，支持用户传ext参数和trace参数
+// 注意这种 case 一定要传 msg 字段
+aegis.info({
+ msg: 'test',
+ ext1: 'ext1',
+ ext2: 'ext2',
+ ext3: 'ext3',
+ trace: 'trace',
+});
+
+// 不同于 info，infoAll 表示全量上报
+aegis.infoAll({
+ msg: 'test',
+ ext1: 'ext1',
+ ext2: 'ext2',
+ ext3: 'ext3',
+ trace: 'trace',
+});
+
+
+// error 用来表示 JS 错误日志，也是全量上报，一般用于开发者主动获取JS异常，然后进行上报
+aegis.error({
+ msg: 'test',
+ ext1: 'ext1',
+ ext2: 'ext2',
+ ext3: 'ext3',
+ trace: 'trace',
+});
+aegis.error(new Error('主动上报一个错误'));
+
+// report 默认是 aegis.report 的日志类型，但是现在你可以传入任何日志类型了
+aegis.report({
+ msg: '这是一个ajax错误日志',
+ level: Aegis.LogType.AJAX_ERROR,
+ ext1: 'ext1',
+ ext2: 'ext2',
+ ext3: 'ext3',
+ trace: 'trace',
 });
 ```
 
+info vs infoAll
+
+1. 使用 “infoAll ” 所有用户都上报，方便排查问题。但是也会带来一定的上报和存储成本。
+2. 使用 “info” 白名单上报。出了问题，可能会缺少关键路径日志。需要添加白名单，重新操作收集日志（类似于染色系统操作）。
+
+## aid
+
+Aegis SDK 为每个用户设备分配的唯一标示，会存储在小程序的 storage 里面，用来区分用户，计算 uv 等。aid 只有用户清理小程序缓存才会更新。
+
+
 ## 实例方法
 
-Aegis 实例暴露接口简单实用，目前 Aegis 实例有以下方法供您使用：  
-`setConfig` 、 `info` 、 `infoAll` 、 `report` 、 `error` 、 `reportEvent` 、 `reportTime` 、 `time` 、 `timeEnd`
+Aegis 实例暴露接口简单实用，目前 Aegis 实例有以下方法供您使用：
+`setConfig` 、 `info` 、 `infoAll` 、 `report` 、 `error` 、 `reportEvent` 、 `reportTime` 、 `time` 、 `timeEnd`、 `destroy`
 
 ### setConfig
 
-该方法用来修改实例配置，比如下面场景：  
-在实例化 Aegis 时需要传入配置对象
+该方法用来修改实例配置，比如下面场景：
+
+- 在实例化 Aegis 时需要传入配置对象。
 
 ```javascript
 const aegis = new Aegis({
-    id: 'pGUVFTCZyewxxxxx',
-    uin: 777
+  id: 'pGUVFTCZyewxxxxx',
+  uin: 777
 })
 ```
 
-很多情况下，并不能一开始就获取到用户的 `uin`，而等获取到用户的 `uin` 才开始实例化 Aegis，如果这期间发生了错误 Aegis 将监听不到。`uin` 的设置可以在获取到用户的时候：
+- 很多情况下，并不能一开始就获取到用户的 `uin`，而等获取到用户的 `uin` 才开始实例化 Aegis，如果这期间发生了错误 Aegis 将监听不到。`uin` 的设置可以在获取到用户的时候：
 
 ```javascript
 const aegis = new Aegis({
-    id: 'pGUVFTCZyewxxxxx'
+  id: 'pGUVFTCZyewxxxxx'
 })
 
 // 拿到uin之后...
 aegis.setConfig({
-    uin: 777
+  uin: 777
 })
 ```
 
@@ -132,24 +209,28 @@ aegis.report(new Error('上报一个错误'));
 
 该方法可用来上报自定义事件，平台将会自动统计上报事件的各项指标，诸如：PV、UV、平台分布等...
 
-reportEvent 可以支持两种类型上报参数类型，一种是字符串类型
+reportEvent 可以支持两种类型上报参数类型。
+
+1. 字符串类型
 
 ```javascript
 aegis.reportEvent('XXX请求成功');
 ```
 
-一种是对象类型，ext1 ext2 ext3 默认使用 new Aegis 的时候传入的参数，自定义事件上报的时候，可以覆盖默认值。
+2. 对象类型，ext1 ext2 ext3 默认使用 new Aegis 的时候传入的参数，自定义事件上报的时候，可以覆盖默认值。
 
 ```javascript
 aegis.reportEvent({
-    name: 'XXX请求成功',
-    ext1: '额外参数1',
-    ext2: '额外参数2',
-    ext3: '额外参数3',
+  name: 'XXX请求成功',
+  ext1: '额外参数1',
+  ext2: '额外参数2',
+  ext3: '额外参数3',
 })
 ```
 
-注意，额外参数的三个 key 是固定的，目前只支持 ext1 ext2 ext3。
+::: warning 注意
+额外参数的三个 key 是固定的，目前只支持 `ext1`、 `ext2`、 `ext3`。
+:::
 
 ### reportTime
 
@@ -164,16 +245,17 @@ aegis.reportTime('onload', 1000);
 
 ```javascript
 aegis.reportTime({
-    name: 'onload', // 自定义测速 name
-    duration: 1000, // 自定义测速耗时(0 - 60000)
-    ext1: 'test1',
-    ext2: 'test2',
-    ext3: 'test3',
+  name: 'onload', // 自定义测速 name
+  duration: 1000, // 自定义测速耗时(0 - 60000)
+  ext1: 'test1',
+  ext2: 'test2',
+  ext3: 'test3',
 });
 ```
 
 > `onload` 可以修改为其他的命名。
 
+
 ### time、timeEnd
 
 该方法同样可用来上报自定义测速，适用于两个时间点之间时长的计算并上报，例如：
@@ -194,6 +276,15 @@ aegis.timeEnd('complexOperation'); /** 此时日志已经报上去了😄**/
 > 自定义测速是用户上报任意值，服务端对其进行统计和计算，因为服务端不能做脏数据处理，因此建议用户在上报端进行统计值限制，防止脏数据对整体产生影响。
 > 目前 Aegis 只支持 0-60000 的数值计算，如果大于该值，建议进行合理改造。
 
+
+### destroy
+
+该方法用于销毁 sdk 实例，销毁后，不再进行数据上报
+
+```javascript
+aegis.destroy();
+```
+
 ## 白名单
 
 白名单功能是适用于开发者希望对某些特定的用户上报更多的日志，但是又不希望太多上报来影响到全部日志数据，并且减少用户的接口请求次数，因为 TAM 设定了白名单的逻辑。
@@ -204,147 +295,130 @@ aegis.timeEnd('complexOperation'); /** 此时日志已经报上去了😄**/
 4. 通过接口 whitelist 来判断当前用户是否是白名单用户，白名单用户的返回结果会绑定在 aegis 实例上 (aegis.isWhiteList) 用来给开发者使用。
 5. 用了减少开发者使用负担，白名单用户是团队有效，可以在 [应用管理-白名单管理](https://console.cloud.tencent.com/rum/web/group-whitelist-manage) 内创建白名单，则团队下全部项目都生效。
 
+
 ## 钩子函数
 
-### beforeReport
+### beforeRequest
 
-该钩子将会在日志上报前执行，例如：
+该钩子将会在日志上报前执行，用于对上报数据的拦截和修改，通过返回不同类型的值：
+* 拦截：返回false
+* 修改：修改入参的值并返回
 
 ```javascript
 const aegis = new Aegis({
-  id: 'pGUVFTCZyewxxxxx',
-  beforeReport(log) {
-    // 监听到下面抛出的错误
-    console.log(log); // {level: "4", msg: "发生错误啦！！！！"}
+  id: "pGUVFTCZyewxxxxx",
+  beforeRequest: function(data) {
+    //入参data的数据结构：{logs: {…}, logType: "log"}
+    if(data.logType === 'log' && data.logs.msg.includes('otheve.beacon.qq.com')){
+      // 拦截：日志类型为log，且内容包含otheve.beacon.qq.com的请求
+      return false;
+    }
+    if(data.logType === 'performance'){
+      // 修改：将性能数据的首屏渲染时间改为2s
+      data.logs.firstScreenTiming = 2000;
+      return data;
+    }
   }
 });
-
-throw new Error('发生错误啦！！！！');
 ```
 
-其中，`log` 将会有以下几个字段：  
+其中，`msg` 将会有以下几个字段：  
 
-> 1.`level`: 日志等级，例如：当 level 为 '4' 时代表错误日志；  
+> 1.`logs`: 上报的日志内容;  
 
-> 2.`msg`: 日志内容；
+> 2.`logType`: 日志类型
 
-全部日志等级如下
+logType等于`custom`时，logs的值如下：
 
 ```sh
-{ level: '1', name: '白名单日志' },
-{ level: '2', name: '一般日志' },
-{ level: '4', name: '错误日志' },
-{ level: '8', name: 'Promise 错误' },
-{ level: '16', name: 'Ajax 请求异常' },
-{ level: '32', name: 'JS 加载异常' },
-{ level: '64', name: '图片加载异常' },
-{ level: '128', name: 'css 加载异常' },
-{ level: '256', name: 'console.error (废弃)' },
-{ level: '512', name: '音视频资源异常' },
-{ level: '1024', name: 'retcode 异常' },
-{ level: '2048', name: 'aegis report' },
-{ level: '16384', name: '页面不存在' },
+{name: "白屏时间", duration: 3015.7000000178814, ext1: '', ext2: '', ext3: '', from: ''}
 ```
 
-当该钩子返回 `false` 时，本条日志将不会进行上报，该功能可用来过滤某些不需要上报的错误，例如：
+logType等于`event`时，logs的值如下：
 
-```javascript
-const aegis = new Aegis({
-  id: 'pGUVFTCZyewxxxxx',
-  beforeReport(log) {
-    if (log.level === '4' && log.msg && log.msg.indexOf('碍眼的错误') !== -1) {
-      return false
-    }
-  }
-});
-throw new Error('碍眼的错误'); // 该错误将不会被上报
+```sh
+{name: "ios", ext1: "", ext2: "", ext3: ""}
 ```
 
-上面例子中，当上报的错误内容包含 `碍眼的错误` 几个关键字时，将不会上报至 RUM 后台中。
-
-### onReport
-
-该钩子将在日志上报成功之后执行，用法类似 `beforeReport` 钩子，唯一不同点在于，该钩子接收到的所有参数都是已经上报完成的日志，而 `beforeReport` 钩子接收的参数是即将上报的日志。
-
-### beforeReportSpeed
+logType等于`log`时，logs的值如下：
 
-该勾子将会在测速数据上报前被执行，例如：
-
-```javascript
-const aegis = new Aegis({
-  id: 'pGUVFTCZyewxxxxx',
-  reportApiSpeed: true,
-  reportAssetSpeed: true,
-  beforeReportSpeed(msg) {
-    console.log(msg); // {url: "https://localhost:3001/example.e31bb0bc.js", method: "get", duration: 7.4, status: 200, type: "static"}
-    return msg
-  }
-});
-```  
-
-其中，`msg` 将会有以下几个字段：  
-
-> 1.`url`: 该资源的请求地址；  
+```sh
+{ level: '1', msg: '接口请求日志（白名单日志）' } // 具体level信息参考日志等级
+```
 
-> 2.`type`: 该资源的类型，目前有 `fetch` 、 `static` 两种，当为 `fetch` 时，Aegis 将会把该资源当成 API 请求进行上报，`static` 时则视为静态资源；  
+logType等于`performance`时，logs的值如下：
 
-> 3.`duration`: 该资源请求耗时；  
+```sh
+{contentDownload: 2, dnsLookup: 0, domParse: 501, firstScreenTiming: 2315, resourceDownload: 2660, ssl: 4, tcp: 4, ttfb: 5}
+```
 
-> 4.`method`: 请求该资源时使用的 `http method`；  
+logType等于`speed`时，logs的值如下：
 
-> 5.`status`: 服务器返回状态码；
+```sh
+// 静态资源
+{connectTime: 0, domainLookup: 0, duration: 508.2, nextHopProtocol: "", isHttps: true, method: "get", status: 200, type: "static", url: "https://puui.qpic.cn/xxx", urlQuery: "max_age=1296000"}
 
-上面的 🌰中，每当 Aegis 收集到一个资源的加载详情时，将会以该资源的加载情况（上面的`msg`）作为参数调用 `beforeReportSpeed` 勾子。  
+// API
+{duration: 26, isErr: 0, isHttps: true, method: "GET", nextHopProtocol: "", ret: "0", status: 200, type: "fetch", url: "https://xx.com/cgi-bin/whoami"}
+```
 
-如果您配置了该勾子，**Aegis 最终的上报内容将以勾子的执行结果为准**。例如：
+logType等于`vitals`时，logs的值如下：
 
-```javascript
-const aegis = new Aegis({
-  id: 'pGUVFTCZyewxxxxx',
-  reportApiSpeed: true,
-  reportAssetSpeed: true,
-  beforeReportSpeed(msg) {
-    msg.type = 'static';
-  }
-});
+```sh
+{CLS: 3.365504747991234, FCP: 139.39999997615814, FID: -1, LCP: 127.899}
 ```
+### modifyRequest
 
-上面的代码中，将所有的 `msg.type` 设置为 `static`，这意味着所有的资源都将被当成静态资源进行上报，API 请求也将被报至静态资源中。  
-
-使用该勾子，您可以校准 Aegis 类型判断错误的请求。  
-比方说，假如您有一条接口 `https://example.com/api`，该接口的响应头 `Content-Type` 为 `text/html`，
-正常情况下，Aegis 会将该资源当成静态资源进行上报。但在您的业务中，该接口就必须视为 API 请求进行上报，您可以给 Aegis 配置如下勾子进行校正：
+该钩子函数会在所有请求发出前调用，参数中会传入请求的所有内容，必须返回待发送内容。
 
 ```javascript
+function changeURLArg(url,arg,arg_val) {
+  var pattern=arg+' = ([^&]*)';
+  var replaceText = arg+'='+arg_val;
+  if (url.match(pattern)) {
+    var tmp = '/('+ arg+'=)([^&]*)/gi';
+    tmp = url.replace(eval(tmp),replaceText);
+    return tmp;
+  }
+  return url;
+}
 const aegis = new Aegis({
   id: 'pGUVFTCZyewxxxxx',
-  reportApiSpeed: true,
-  reportAssetSpeed: true,
-  beforeReportSpeed(msg) {
-    if (msg.url === 'https://example.com/api') {
-      msg.type = 'fetch';
+  modifyRequest(options) {
+    if (options.type === 'performance') {
+      // 页面测速，此时可以修改options内容，如修改页面测速platform
+      options.url = changeURLArg(options.url, 'platform', type)
     }
+    return options
   }
 });
 ```
+### afterRequest
 
-您还可以屏蔽某些资源的测速上报，例如：
+该勾子将会在数据上报后被执行，例如：
 
 ```javascript
 const aegis = new Aegis({
-  id: 'pGUVFTCZyewxxxxx',
+  id: "pGUVFTCZyewxxxxx",
   reportApiSpeed: true,
   reportAssetSpeed: true,
-  beforeReportSpeed(msg) {
-    // 地址中包含‘https://example.com/api’的都不上报
-    if (msg.url.indexOf('https://example.com/api') !== -1) {
-      // 返回 ‘false’ 将阻止本条测速日志的上报
-      return false
-    }
+  afterRequest: function(msg) {
+    // {isErr: false, result: Array(1), logType: "log", logs: Array(4)}
+    console.log(msg);
   }
 });
 ```
 
+其中，`msg` 将会有以下几个字段：  
+
+> 1.`isErr`: 请求上报接口是否错误；  
+
+> 2.`result`: 上报接口的返回结果；  
+
+> 3.`logs`: 上报的日志内容;
+
+> 4.`logType`: 日志类型，有以下值speed：接口和静态资源测速，performance：页面测速，vitals：web vitals，event：自定义事件，custom：自定义测速;
+
 ## 错误监控
 
 ::: warning
@@ -353,56 +427,108 @@ Aegis 的实例会自动进行以下监控，注意！是 Aegis 实例会进行
 
 ### JS执行错误
 
-Aegis 通过监听 `wx.onerror` 事件来获取项目中的报错，并且通过解析错误和分析堆栈，将错误信息自动上报到后台服务中。该上报的上报等级为 error ，所以，当自动上报的错误达到阈值时，Aegis 将会自动告警，帮助您尽早发现异常。由于上报等级为 error ，自动上报也将影响项目的每日评分。
+Aegis 通过监听 `window` 对象上的 `onerror` 事件来获取项目中的报错，并且通过解析错误和分析堆栈，将错误信息自动上报到后台服务中。该上报的上报等级为 error ，所以，当自动上报的错误达到阈值时，Aegis 将会自动告警，帮助您尽早发现异常。由于上报等级为 error ，自动上报也将影响项目的每日评分。
 
-### Promise执行错误
+### request 请求异常
 
-通过监听 `wx.onUnhandledRejection` 事件，捕获到未被 `catch` 的Promise错误，为了页面的健壮，建议您 `catch` 住所有的Promise错误哟。
+Aegis 将会改写 `wx.request`(`qq.request`) 对象（请您放心，Aegis很专业），监听每次接口请求，当 `statusCode` 不存在或者大于等于 400 时认为该请求是一个失败的请求，亦或是接口超时，abort 和其他类型的失败。
 
-### 页面不存在错误
+注意： Aegis SDK 在错误发生的时候，不会主动收集接口请求参数和返回信息，如果需要对进口信息进行上报，可以使用 api 参数里面的 apiDetail 进行开启。
 
-通过监听 `wx.onPageNotFound` 事件，捕获小程序要打开的页面不存在错误。
+```javascript
+new Aegis({
+  id: '',
+  api: {
+    apiDetail: true,
+  },
+});
+```
 
-### request 请求异常
+### retcode异常
 
-Aegis 将会改写 `wx.request`(`qq.request`) 对象，监听每次接口请求，当 `statusCode` 大于 400 时将认为该请求是一个失败的请求。  
+同上，Aegis 在改写 `wx.request`(`qq.request`) 对象之后，将获得API返回的内容，并尝试在内容中获取到本次请求的 `retcode`。
 
-### 返回码异常
+> retcode 的值会从用户返回 response body 的第一层（如果第一层取不到，再取第二层）的 code、ret、retcode、errcode 中获取。
+> Aegis 默认 retcode 的值为0是正常的，非0都是异常的。当 `retcode` 发生异常的时候，会上报一个 retcode异常的日志。
+> 用户可以通过 api.retCodeHandler 对这个值和是否异常进行修正。
 
-同上，Aegis 在改写 `wx.request`(`qq.request`) 对象之后，将获得API返回的内容，并尝试在内容中获取到本次请求的 `retcode`，
-当 `retcode` 不符合预期的时候，会认为本次请求出现了异常，并进行上报。
-> 如何获取 `retcode` 以及哪些 `retcode` 是正常的可以在配置文档中查看。
+### websocket异常
+Aegis默认不会对全局websocket对象进行重写，默认不会监控websocket相关错误，如果需要打开相关功能可以在创建Aegis对象时设置websocketHack: true。
+```javascript
+new Aegis({
+  id: '',
+  websocketHack: true
+});
+```
 
 ## 性能监控
+### 页面性能
+
+> Aegis 小程序 SDK 会自动收集页面性能数据并上报。包括：
+1. 程序启动时间
+2. 代码注入时间
+3. 页面首次渲染时间
+4. 路由切换时间
+
+::: warning 注意 ⚠️
+获取页面性能数据依赖小程序的 Performance API，请保证基础库版本 `>2.11.0`。
+手Q小程序目前暂时不支持 Performance API，所以不会上报页面性能数据。
+:::
+
+
+### 组件更新性能(setData)
+
+> Aegis 小程序 SDK 默认会自动获取组件的更新性能数据并上报，便于对组件针对性优化。
+
+::: warning 注意 ⚠️
+获取更新性能统计信息依赖小程序框架提供的API `setUpdatePerformanceListener`，请保证基础库版本 `>2.12.0`。
+详情可以参考[这里](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/update-perf-stat.html)。
+:::
+
+::: warning 注：
+某些应用场景下的小程序项目可能数据更新很频繁从而导致上报请求过多，因此 sdk 针对 setData 数据上报提供了额外的配置项，具体可见下方`配置文档`中的`setDataReportConfig`配置项。
+:::
 
-### 页面测速
 
-Aegis SDK 通过收集小程序的 performance 信息来对您的页面进行测速。
 ### 接口测速
 
-> 打开方式：初始化时传入配置 `reportApiSpeed: true`  
+> 打开方式：初始化时传入配置 `reportApiSpeed: true`
 
-Aegis 通过劫持 `wx.request || qq.request` 进行接口测速。
+Aegis 通过劫持 `wx.request || qq.request` 进行接口测速，具体代码在 [这里](https://git.code.oa.com/tam/aegis-sdk/blob/master/packages/mp-sdk/src/plugins/cgi-speed.ts)
 
-## 配置文档
 
+## 配置文档
 | 配置 | 描述 |
 | -------- | -------- |
-| id | 必须，number，默认 无。<br>开发者平台分配的项目key |
-| uin | 建议，string，默认取 cookie 中的 uin 字段。<br>当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持`字母数字@=._-`，正则表达式: `/^[@=.0-9a-zA-Z_-]{1,60}$/` |
+| id | 必须，string，默认 无。<br>开发者平台分配的项目上报ID |
+| uin | 建议，string <br>业务定义的当前用户的唯一标识符，用来查找固定用户的日志。白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持`字母数字@=._-`，正则表达式: `/^[@=.0-9a-zA-Z_-]{1,60}$/` |
+| onError | 可选，boolean，默认 true。<br>当前实例是否需要进行错误监听，获取错误日志 |
 | reportApiSpeed | 可选，boolean，默认 false。<br>是否开启接口测速 |
+| reportAssetSpeed | 可选，boolean，默认 false。<br>是否开启静态资源测速 |
+| reportLoadPackageSpeed | 可选，boolean，默认 true。<br>是否开启包下载耗时上报 |
+| pagePerformance | 可选，boolean 默认 true。<br>是否开启页面测速 |
 | version | 可选，string，默认 sdk 版本号。<br>当前上报版本，当页面使用了pwa或者存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持`字母数字.,:_-`，长度在 60 位以内 `/^[0-9a-zA-Z.,:_-]{1,60}$/` |
 | delay | 可选，number，默认 1000 ms。<br>上报节流时间，在该时间段内的上报将会合并到一个上报请求中。 |
 | repeat | 可选，number，默认 5。<br>重复上报次数，对于同一个错误超过多少次不上报。 |
-| enableHttp2 | 可选，boolean，默认 false。<br> 上报数据是否支持 HTTP2，默认没有开启，以后会考虑改成默认开启。 |
+| env | 可选，enum，默认 Aegis.environment.production。 <br> 当前项目运行所处的环境。｜
+| spa | 可选，boolean，默认 false。 <br> 当前页面是否是单页应用？true的话将会监听hashchange及history api，在页面跳转时进行pv上报 |
+| pageUrl | 可选，string，默认是小程序 getCurrentPages。 <br> 修改上报数据中页面地址，开发者可以主动对数据进行聚合和降低维度｜
+| urlHandler | 可选，Function。 <br> 动态修改上报数据中页面地址 from，可以配合 pageUrl 参数使用｜
 | websocketHack | 可选，boolean，默认 false <br>是否开启websocket监控。 |
+| enableHttp2 | 可选，boolean，默认 false。<br> 上报数据是否支持 HTTP2，默认没有开启。 |
 | offlineLog | 可选，boolean，默认 false。<br>是否使用离线日志 |
 | offlineLogExp | 可选，number，默认 3。<br>离线日志过期天数 |
-| url | 可选，string，默认 '//aegis.qq.com/collect'。<br>日志上报地址 |
-| speedUrl | 可选，string，默认 '//aegis.qq.com/speed'。<br>测速日志上报地址 |
-| performanceUrl | 可选，string，默认 '//aegis.qq.com/speed/performance'。<br>页面性能日志上报地址 |
-| whiteListUrl | 可选，string，默认 '//aegis.qq.com/collect/whitelist'。<br>白名单确认接口 <br>如果想要关闭白名单接口请求，可以传空字符串|
-| api | 可选，object，默认为{}。相关的配置: <br> apiDetail : 可选，boolean，默认false。api 失败的时候，是否上报 api 的请求参数和返回值； <br> retCodeHandler: Function， 返回码上报钩子函数。 会传入接口返回数据，返回值为{isErr: boolean, code: string}。<span id="jump">[见示例[1]](#exp1)</span> |
+| hostUrl | 可选，默认是 `https://aegis.qq.com`。<br>影响全部上报数据的 host 地址，下面几个 url 地址设置后会覆盖对应的上报地址 ｜
+| url | 可选，string，默认 'https://aegis.qq.com/collect'。<br>日志上报地址 |
+| pvUrl | 可选，string, 默认 'https://aegis.qq.com/collect/pv' <br> pv 上报地址 ｜
+| whiteListUrl | 可选，string，默认 'https://aegis.qq.com/collect/whitelist'。<br>白名单确认接口 <br>如果想要关闭白名单接口请求，可以传空字符串|
+| offlineUrl | 可选，string，默认 'https://aegis.qq.com/collect/offline'。<br> 离线日志上报地址 |
+| eventUrl | 可选，string，默认 'https://aegis.qq.com/collect/events'。<br> 自定义事件上报地址 |
+| speedUrl | 可选，string，默认 'https://aegis.qq.com/speed'。<br>测速日志上报地址 |
+| customTimeUrl | 可选，string，默认 'https://aegis.qq.com/speed/custom'。<br>自定义测速上报地址 |
+| performanceUrl | 可选，string，默认 'https://aegis.qq.com/speed/performance'。<br>页面性能日志上报地址 |
+| setDataReportConfig | 可选，object，默认为{}。相关的配置: <br> disabled: 可选，Boolean，默认false。是否禁用setData数据上报; <br> timeThreshold: 可选，Number，单位为ms，默认值为30。上报的耗时阈值，表示仅上报更新耗时超过该阈值的数据；<br> withDataPaths: 可选，Boolean，默认为true。是否上报本次更新的字段信息；|
+| api | 可选，object，默认为 {}。相关的配置:  <br> apiDetail : 可选，boolean，默认false。上报 api 信息的时候，是否上报 api 的请求参数和返回值; <br><br> retCodeHandler: Function(data: String, url: String, xhr: Object):{isErr: boolean, code: string}， 返回码上报钩子函数。 会传入接口返回数据,请求url和xhr对象; <br><br> reqParamHandler: Function(data: any, url: String) 上报请求参数的处理函数，可以对接口的请求参数进行处理，方便用户过滤上报请求参数的信息; <br><br> resBodyHandler: Function(data: any, url: String) 上报 response 返回 body 的处理函数，可以对接口返回值的 response body 进行处理，只上报关键信息; <br><br> reqHeaders: Array 需要上报的 http 请求 request headers 列表。 <br><br> resHeaders: Array 需要上报的 http 请求 response headers 列表。 <br><br> resourceTypeHandler: Function，请求资源类型修正钩子函数 会传入接口url，返回值为‘static’或‘fetch’。<span id="jump">[见示例[1]](#exp1)</span> <br><br> reportRequest: boolean, 默认为false。 开启aegis.info全量上报, 不需要白名单配置。并上报所有接口请求信息（请开启reportApiSpeed） |
 | ext1 | 可选，string，自定义上报的额外维度，上报的时候可以被覆盖 |
 | ext2 | 可选，string，自定义上报的额外维度，上报的时候可以被覆盖 |
 | ext3 | 可选，string，自定义上报的额外维度，上报的时候可以被覆盖 |
@@ -413,25 +539,27 @@ Aegis 通过劫持 `wx.request || qq.request` 进行接口测速。
 
 ```json
 {
-    body: {
-        code: 200,
-        retCode: 0,
-        data: {
-            // xxx
-        }
+  body: {
+    code: 200,
+    retCode: 0,
+    data: {
+      // xxx
     }
+  }
 }
+
 ```
 
 业务需要：code不为200，或者retCode不为0，此次请求就是错误的。此时只需进行以下配置：
 
 ```javascript
 new Aegis({
-  reportApiSpeed: true, // 需要开两个，不然不会有返回码上报
+  // xxx
+  reportApiSpeed: true, // 需要开启，不然不会有返回码上报
   reportAssetSpeed: true,
   api: {
-    retCodeHandler(data) { 
-        // 注意这里拿到的data是string类型，如果需要对象需要手动parse下
+    retCodeHandler(data) {
+      // 注意这里的data的数据类型，跟接口返回值的数据类型一致，开发者需要根据实际情况自行处理
       try {
         data = JSON.parse(data)
       } catch(e) {}