aegis-mp-mini-sdk
v0.0.3
Published
aegis sdk for wechat and qq mini program
Downloads
2
Readme
aegis-mp-sdk
Aegis(读音/ˈiːdʒɪs/) 是腾讯云监控团队提供的前端监控 SDK,涵盖了错误监控,资源测速(img, script, css),接口测速,页面性能(首屏时间)。无需侵入代码,只需引入 SDK 即可自动完成所有监控上报。
在使用 aegis 时无需在业务代码中打点或者做任何其他操作,可以做到与业务代码充分解耦。aegis 将会自动监控前端错误,在错误发生时上报错误的具体情况,帮助您快速定位问题。当您开启资源测速时,aegis 将会自动监听页面资源加载情况(耗费时长、成功率等),并在不影响前端性能的前提下收集前端的性能数据,帮助您快速定位性能短板,提升用户体验。
使用本 SDK 需要配合使用腾讯云前端性能监控 RUM 平台。
aegis-mp-sdk 是针对微信小程序和QQ小程序开发的数据收集和上报 SDK。
本 SDK 是 Aegis mini SDK,用于开发者包装后二次使用,比如模块内部使用。该 SDK 不会主动收集任何信息,需要开发者引入后自动上报。
使用
初始化
使用非常简单,只需要新建一个 Aegis 实例,传入相应的配置即可:
import Aegis from 'aegis-mp-sdk';
const aegis = new Aegis({
id: "pGUVFTCZyewxxxxx", // 项目key
uin: 'xxx', // 用户唯一 ID(可选)
})
::: warning 注意 ⚠️ 为了不遗漏数据,须尽早进行初始化; :::
::: tip 当您做了以上接入工作之后,您已经开始享受 Aegis 提供的以下功能:
1、错误监控:JS执行错误;
2、测速:接口测速;
3、数据统计和分析:可在 RUM 平台 上查看各个纬度的数据分析;
:::
日志上报
创建完 Aegis 实例之后,就可以开心的上报日志啦 🥰,日志上报同样简单
在 mini sdk 中,因为没有白名单机制, info 与 infoAll 的用法完全相同
aegis.info(
`我是一条普通的信息`
);
aegis.infoAll(
`我是一条普通的信息`
);
aegis.report(
new Error('我是一条错误信息,推荐在try..catch或者Promise.reject中使用。')
);
aegis.report({
msg: '这是一个ajax错误日志',
level: Aegis.LogType.AJAX_ERROR,
});
aid
Aegis SDK 为每个用户设备分配的唯一标示,会存储在小程序的 storage 里面,用来区分用户,计算 uv 等。aid 只有用户清理小程序缓存才会更新。
算法如下:
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;
},
});
实例方法
Aegis 实例暴露接口简单实用,目前 Aegis 实例有以下方法供您使用:setConfig
、 info
、 infoAll
、 report
、 error
、 reportEvent
、 reportTime
、 time
、 timeEnd
setConfig
该方法用来修改实例配置,比如下面场景:
在实例化 Aegis 时需要传入配置对象
const aegis = new Aegis({
id: 'pGUVFTCZyewxxxxx',
uin: 777
})
很多情况下,并不能一开始就获取到用户的 uin
,而等获取到用户的 uin
才开始实例化 Aegis,如果这期间发生了错误 Aegis 将监听不到。uin
的设置可以在获取到用户的时候:
const aegis = new Aegis({
id: 'pGUVFTCZyewxxxxx'
})
// 拿到uin之后...
aegis.setConfig({
uin: 777
})
reportEvent
该方法可用来上报自定义事件,平台将会自动统计上报事件的各项指标,诸如:PV、UV、平台分布等...
reportEvent 可以支持两种类型上报参数类型,一种是字符串类型
aegis.reportEvent('XXX请求成功');
一种是对象类型,ext1 ext2 ext3 默认使用 new Aegis 的时候传入的参数,自定义事件上报的时候,可以覆盖默认值。
aegis.reportEvent({
name: 'XXX请求成功',
ext1: '额外参数1',
ext2: '额外参数2',
ext3: '额外参数3',
})
注意,额外参数的三个 key 是固定的,目前只支持 ext1 ext2 ext3。
reportTime
该方法可用来上报自定义测速,例如:
// 假如‘onload’的时间是1s
aegis.reportTime('onload', 1000);
或者如果需要使用额外参数,可以传入对象类型参数,ext1,ext2,ext3 会覆盖默认值:
aegis.reportTime({
name: 'onload', // 自定义测速 name
duration: 1000, // 自定义测速耗时(0 - 60000)
ext1: 'test1',
ext2: 'test2',
ext3: 'test3',
});
onload
可以修改为其他的命名。
time、timeEnd
该方法同样可用来上报自定义测速,适用于两个时间点之间时长的计算并上报,例如:
aegis.time('complexOperation');
/**
* .
* .
* 做了很久的复杂操作之后。。。
* .
* .
*/
aegis.timeEnd('complexOperation'); /** 此时日志已经报上去了😄**/
complexOperation
同样可以修改为其他的命名。 自定义测速是用户上报任意值,服务端对其进行统计和计算,因为服务端不能做脏数据处理,因此建议用户在上报端进行统计值限制,防止脏数据对整体产生影响。 目前 Aegis 只支持 0-60000 的数值计算,如果大于该值,建议进行合理改造。
钩子函数
onReport
该钩子将在日志上报成功之后执行,用法类似 beforeReport
钩子,唯一不同点在于,该钩子接收到的所有参数都是已经上报完成的日志,而 beforeReport
钩子接收的参数是即将上报的日志。
错误监控
::: warning Aegis 的实例会自动进行以下监控,注意!是 Aegis 实例会进行监控,当您只是引入了 SDK 而没有将其实例化时,Aegis 将什么都不会做。 :::
JS执行错误
Aegis 通过监听 window
对象上的 onerror
事件来获取项目中的报错,并且通过解析错误和分析堆栈,将错误信息自动上报到后台服务中。该上报的上报等级为 error ,所以,当自动上报的错误达到阈值时,Aegis 将会自动告警,帮助您尽早发现异常。由于上报等级为 error ,自动上报也将影响项目的每日评分。
request 请求异常
Aegis 将会改写 wx.request
(qq.request
) 对象,监听每次接口请求,当 statusCode
大于 400 时将认为该请求是一个失败的请求。
返回码异常
同上,Aegis 在改写 wx.request
(qq.request
) 对象之后,将获得API返回的内容,并尝试在内容中获取到本次请求的 retcode
,
当 retcode
不符合预期的时候,会认为本次请求出现了异常,并进行上报。
如何获取
retcode
以及哪些retcode
是正常的可以在配置文档中查看。
性能监控
页面测速
Aegis SDK 通过收集小程序的 performance 信息来对您的页面进行测速。
接口测速
打开方式:初始化时传入配置
reportApiSpeed: true
Aegis 通过劫持 wx.request || qq.request
进行接口测速。
配置文档
| 配置 | 描述 |
| -------- | -------- |
| id | 必须,number,默认 无。开发者平台分配的项目key |
| uin | 建议,string,默认取 cookie 中的 uin 字段。当前用户的唯一标识符,白名单上报时将根据该字段判定用户是否在白名单中,字段仅支持字母数字@=._-
,正则表达式: /^[@=.0-9a-zA-Z_-]{1,60}$/
|
| reportApiSpeed | 可选,boolean,默认 false。是否开启接口测速 |
| version | 可选,string,默认 sdk 版本号。当前上报版本,当页面使用了pwa或者存在离线包时,可用来判断当前的上报是来自哪一个版本的代码,仅支持字母数字.,:_-
,长度在 60 位以内 /^[0-9a-zA-Z.,:_-]{1,60}$/
|
| delay | 可选,number,默认 1000 ms。上报节流时间,在该时间段内的上报将会合并到一个上报请求中。 |
| repeat | 可选,number,默认 5。重复上报次数,对于同一个错误超过多少次不上报。 |
| url | 可选,string,默认 '//aegis.qq.com/collect'。日志上报地址 |
| speedUrl | 可选,string,默认 '//aegis.qq.com/speed'。测速日志上报地址 |
| whiteListUrl | 可选,string,默认 '//aegis.qq.com/collect/whitelist'。白名单确认接口 如果想要关闭白名单接口请求,可以传空字符串|
| api | 可选,object,默认为{}。相关的配置: retCodeHandler: Function, 返回码上报钩子函数。 会传入接口返回数据,返回值为{isErr: boolean, code: string}。见示例[1] |
| enableHttp2 | 可选,boolean,默认 false。 数据上报接口是否开启 HTTP2 |
| ext1 | 可选,string,自定义上报的额外维度,上报的时候可以被覆盖 |
| ext2 | 可选,string,自定义上报的额外维度,上报的时候可以被覆盖 |
| ext3 | 可选,string,自定义上报的额外维度,上报的时候可以被覆盖 |
示例
[1] retCodeHandler,假如后台返回数据为:
{
body: {
code: 200,
retCode: 0,
data: {
// xxx
}
}
}
业务需要:code不为200,或者retCode不为0,此次请求就是错误的。此时只需进行以下配置:
new Aegis({
reportApiSpeed: true, // 需要开两个,不然不会有返回码上报
reportAssetSpeed: true,
api: {
retCodeHandler(data) {
// 注意这里拿到的data是string类型,如果需要对象需要手动parse下
try {
data = JSON.parse(data)
} catch(e) {}
return {
isErr: data.body.code !== 200 || data.body.retCode !== 0,
code: data.body.code
}
}
}
})