一、配置说明
配置文档各配置项说明如下：
| 配置 | 描述 |
| id | 必须，string，默认无。前端性能监控分配的应用 ID。 |
| uin | 建议，string，默认取 cookie 中的 UIN 字段。当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持字母数字@=._-，正则表达式：/^[@=.0-9a-zA-Z_-]{1,60}$/。 |
| reportApiSpeed | 可选，boolean 或者 object，默认 false。是否开启接口测速，这个开关设置为 true 后，还需在 白名单管理 页面将用户添加为白名单用户，才会将采集到的正常的 api 请求记录到日志中，否则仅在指标分析模块聚合消费。 |
| reportAssetSpeed | 可选，boolean，默认 false。是否开启静态资源测速。 |
| pagePerformance | 可选，boolean 或者 object，默认 true。是否开启页面测速。 |
| webVitals | 可选，boolean，默认 true。是否开启 web vitals 测速。 |
| blankScreen | 可选，boolean，默认 false。是否开启白屏监控。 |
| consoleLog | 可选，boolean，默认 false。是否将采集的 console 日志上报为日志。 |
| clickElementLog | 可选，boolean，默认 false。是否将采集的点击事件上报为日志。 |
| ignoreElements | 可选，{"ignoreClasses": string[], "ignoreIds": string[]}，例如 { "ignoreClasses": ["address-box","school-box"], "ignoreIds": ["phone-num-card","name-card"]},通过元素的 class 和 id 忽略指定元素，用于过滤掉不需要上报的元素，例如用户的个人信息输入框等。 |
| slowApiLog | 可选，boolean，默认 false。是否将采集的慢 api 请求数据上报为日志，慢的标准是请求耗时超过1000ms。 |
| pageLoadLog | 可选，boolean，默认 false。是否将采集的正常页面加载数据上报为日志。 |
| slowPageLoadLog | 可选，boolean，默认 false。是否将采集的慢页面加载数据上报为日志，慢的标准是 fmp 超过1000ms。 |
| assetLog | 可选，boolean，默认 false。是否将采集的正常资源请求数据上报为日志，这个开关设置为 true 后，还需在 白名单管理 页面将用户添加为白名单用户，才会将采集到的正常的资源请求记录到日志中，否则仅在指标分析模块聚合消费。 |
| slowAssetLog | 可选，boolean，默认 false。是否将采集的慢资源请求数据上报为日志，慢的标准是请求耗时超过1000ms。 |
| onError | 可选，boolean，默认 true。当前实例是否需要进行错误监听，获取错误日志。 |
| aid | 可选，boolean，默认 true。当前实例是否生成 aid。 |
| random | 可选，number，默认 1。0 – 1 抽样率。 0 表示全部不上报。 |
| spa | 可选，boolean，默认 false。 当前页面是否为单页应用，若为 true，则将监听 hashchange 及 history api，在页面跳转时进行 PV 上报。 |
| pageUrl | 可选。默认是 location.href。 修改上报数据中页面地址，开发者可以主动对数据进行聚合和降低维度。 |
| version | 可选，string，默认 SDK 版本号。当前上报版本，当页面使用了 pwa 或者存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持字母数字.,:_-，长度在 60 位以内 /^[0-9a-zA-Z.,:_-]{1,60}$/。 |
| delay | 可选，number，默认 1000ms。上报节流时间，在该时间段内的上报将会合并到一个上报请求中。 |
| repeat | 可选，number，默认 5。重复上报次数，对于同一个错误超过多少次后不上报。同一个接口上报测速数据的次数。 |
| env | 可选 enum，默认 Aegis.environment.production。当前应用运行所处的环境，详情请参见说明文档 环境控制。 |
| websocketHack | 可选，boolean，默认 false。 是否开启 websocket 监控。开启该选项后，将会对 websocket 连接断开状态进行监控，但是新建操作仍需要自定义监控。 |
| api | 可选，object，默认为 {}。相关的配置：apiDetail：可选，boolean，默认false。上报 api 信息的时候，是否上报 api 的请求参数和返回值。retCodeHandler：Function(data: String, url: String, xhr: Object):{isErr: boolean, code: string}， 返回码上报钩子函数。 会传入接口返回数据，请求 url 和 xhr 对象；详情请参见示例 api.retCodeHandler。reqParamHandler：Function(data: any, url: String) 上报请求参数的处理函数，可以对接口的请求参数进行处理，方便用户过滤上报请求参数的信息。resBodyHandler：Function(data: any, url: String) 上报 response 返回 body 的处理函数，可以对接口返回值的 response body 进行处理，只上报关键信息。resourceTypeHandler：Function，请求资源类型修正钩子函数会传入接口 url，返回值为static或 fetch。reportRequest：boolean，默认：false。开启后，aegis.info 会变成全量上报，不需要白名单配置，并且会上报所有接口的信息（上报接口需开启 reportApiSpeed）。reqHeaders：Array 需要上报的 HTTP 请求 request headers 列表。resHeaders：Array 需要上报的 HTTP 请求 response headers 列表。如果开发者需要获取的字段非 “simple response header”，需要在返回头中给字段添加 Access-Control-Expose-Headers。usePerformanceTiming：boolean，默认：false。aegis sdk 默认使用打点的方式计算接口耗时，该方式在移动端存在一些误差，开启 usePerformanceTiming 后，aegis sdk 会从 performance 中重新获取接口耗时，让接口耗时统计更为准确。需要注意的是，开启该参数的前提是用户业务接口请求 url 是独立且唯一的，用户可以在接口请求 url 中添加时间戳等方式来保证 url 唯一性。如果 url 不唯一，可能导致同 url 接口耗时获取错误。injectTraceHeader：可选，string，且必须为枚举值 'traceparent'、'sw8'、'b3'、'sentry-trace' 中的一种，开启该参数后，Aegis 会在用户请求头中注入相关 trace header。详细用法参考 腾讯云可观测平台全链路接入。injectTraceUrls：可选，Array，数组中传入 string 或者 RegExp。标记哪些请求 url 需要注入 trace 请求头。injectTraceIgnoreUrls：可选，Array，数组中传入 string 或者 RegExp。标记哪些请求 url 不需要注入 trace 请求头。 |
| lagMonitor | 可选，object，默认为 {}。相关配置如下：enabled：boolean，默认为 false。如果需要开启卡顿监控，设置为 true。threshold：可选，number，默认为2000。卡顿阈值，单位为毫秒。noResponseThreshold：可选，number，默认为5000。无响应阈值，单位为毫秒。 |
| memoryMonitor | 可选，object，默认为 {}。相关配置如下：enabled：boolean，默认为 false。如果需要开启内存监控，设置为 true。enableMemoryReport：boolean，默认为 true。是否启用定时上报内存值功能，如果仅需 OOM 检测，设置为 false。enableOOMReport：boolean，默认为 true。是否启用 OOM 检测，如果仅需定时内存上报，设置为 false。oomThreshold：number，默认为内存上限的90%。OOM 阈值，单位为MB。memoryReportInterval：number，默认60000。内存上报间隔，单位毫秒。oomCheckInterval：number，默认10000。OOM 检测间隔，单位为毫秒。 |
| speedSample | 可选，boolean，默认 true。测速日志是否抽样（限制每条 url 只上报一次测速日志）。 |
| ext1 | 可选，string，自定义上报的额外维度，上报的时候可以被覆盖，长度限制为1024，超过1024时会被截断。 |
| ext2 | |
| ext3 | |
| ext4 | 可选，string，自定义上报的额外维度。如你需要使用 ext4 – ext10的扩展字段，你还需要在 前端性能监控 > 应用管理 > 字段映射配置 模块上传自定义字段枚举表，以确保 ext4 – ext10的内容展示为你预期的效果。上报的内容如果不在自定义字段枚举表内，会被改写为 undefined。如果自定义事件、日志上报时包含 ext4 – ext10字段，会覆盖全局的配置上报。 |
| ext5 | |
| ext6 | |
| ext7 | |
| ext8 | |
| ext9 | |
| ext10 | |
二、api.retCodeHandler
假如后台返回数据为：
new Aegis({ // xxx reportApiSpeed: true, // 需要开两个，不然不会有返回码上报 reportAssetSpeed: true, api: { retCodeHandler(data, url, xhr) { // data 是string类型，如果需要对象需要手动parse下 // url 为请求url // xhr 响应,可以通过xhr.response拿到完整的后台响应 try { data = JSON.parse(data) } catch(e) {} return { // isErr 如果是 true 的话，会上报一条 retcode 异常的日志。 isErr: data.body.code !== 200 || data.body.retCode !== 0, code: data.body.code } } }})
三、api.resourceTypeHandler
假如接口为：http://example.com/test-api 。返回的 Content-Type 为 text/html，这将导致 Aegis 认为该接口返回的是静态资源，可以通过以下方法修正：
new Aegis({ reportApiSpeed: true, // 需要开两个，不然不会有返回码上报 reportAssetSpeed: true, api: { resourceTypeHandler(url) { if (url?.indexOf('http://example.com/test-api') != -1) { return 'fetch'; } } }})
四、reportApiSpeed.urlHandler
假如你页面中有 restful 风格的接口，例如：
www.example.com/user/1000
www.example.com/user/1001
在上报测速时需要将这些接口聚合：
new Aegis({ // xxx reportApiSpeed: { urlHandler(url, payload) { if ((/www\\.example\\.com\\/user\\/\\d*/).test(url)) { return 'www.example.com/user/:id'; } return url; } } // xxx})
五、pagePerformance.urlHandler
假如你的页面 URL 是 restful 风格的，例如：
www.example.com/user/1000
www.example.com/user/1001
在上报页面测速时需要将这些页面地址聚合：
new Aegis({ // xxx pagePerformance: { urlHandler() { if ((/www\\.example\\.com\\/user\\/\\d*/).test(window.location.href)) { return 'www.example.com/user/:id'; } } } // xxx})