aegis-uniapp-sdk

v0.2.0

Published

4 days ago

aegis sdk for uniapp wgt

0High
0Medium
0Low

libinnlli

aegis-uniapp-sdk

Aegis 是腾讯云监控团队提供的前端监控 SDK，涵盖了错误监控、接口测速、接口异常、WebSocket 异常、设备信息和手动静态资源测速。

使用本 SDK 需要配合使用腾讯云前端性能监控 RUM 平台。

aegis-uniapp-sdk 是针对 uniapp 打包成 wgt 资源包并运行在 App 端 的数据收集和上报 SDK。

其他平台请使用对应 SDK：小程序 → aegis-mp-sdk，H5 → aegis-web-sdk。

使用

安装

在项目支持 NPM 时推荐使用 NPM 安装 Aegis SDK。

npm install --save aegis-uniapp-sdk

初始化

使用非常简单，只需要新建一个 Aegis 实例，传入相应的配置即可。

:::: warning 注意 ⚠️ 为了尽早注册错误、请求和 WebSocket 监听，SDK 必须在创建 App 之前初始化。

App 端正式环境需要确保上报域名可访问。SDK 默认使用 https://rumt-zh.com 作为上报域名。 ::::

Vue 2（main.js）

import Vue from 'vue';
import App from './App';
import Aegis from 'aegis-uniapp-sdk';

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx', // 项目上报 ID
  uin: 'xxx', // 用户唯一 ID（可选）
  reportApiSpeed: true, // 接口测速和请求异常监控
  reportAssetSpeed: true, // 手动静态资源测速
  websocketHack: true, // WebSocket 异常监控
  hostUrl: 'https://rumt-zh.com', // 上报域名，中国大陆 rumt-zh.com
});

Vue.prototype.$aegis = aegis;

App.mpType = 'app';
const app = new Vue({
  ...App,
});
app.$mount();

Vue 3（main.js）

import { createSSRApp } from 'vue';
import App from './App.vue';
import Aegis from 'aegis-uniapp-sdk';

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx', // 项目上报 ID
  uin: 'xxx', // 用户唯一 ID（可选）
  reportApiSpeed: true, // 接口测速和请求异常监控
  reportAssetSpeed: true, // 手动静态资源测速
  websocketHack: true, // WebSocket 异常监控
  hostUrl: 'https://rumt-zh.com', // 上报域名，中国大陆 rumt-zh.com
});

export function createApp() {
  const app = createSSRApp(App);
  app.config.globalProperties.$aegis = aegis;
  return {
    app,
  };
}

如果使用 ES 模块的方式引入 Aegis 后报错，可以通过如下方式解决：

方法一：在 tsconfig.json 中设置 esModuleInterop: true，然后通过 import Aegis from 'aegis-uniapp-sdk' 引入。

方法二：import * as Aegis from 'aegis-uniapp-sdk'。

方法三：const Aegis = require('aegis-uniapp-sdk')。

:::: tip 当您完成以上接入后，您已经开始享受 Aegis 提供的以下功能：

错误监控：JS 执行错误、Promise 错误；
测速：接口测速、手动静态资源测速；
异常监控：请求异常、retcode 异常、WebSocket 异常；
数据统计和分析：可在 RUM 平台上查看各个维度的数据分析。 ::::

支持的监控能力

| 功能 | 说明 | 开启方式 | |------|------|---------| | JS Error | App.onError、Vue errorHandler 捕获 | 默认开启 | | Promise Error | App.onUnhandledRejection 捕获（HBuilderX 3.1+） | 默认开启 | | 接口请求测速 & 异常 | 拦截 uni.request / uni.uploadFile / uni.downloadFile | reportApiSpeed: true | | WebSocket 异常 | 拦截 uni.connectSocket，监听连接失败 / onError / send fail | websocketHack: true | | 页面性能 | 通过 pagePerformanceMixin 统计 App 启动耗时、页面加载耗时 | pagePerformance: true | | 页面流转（SPA/PV） | 拦截 uni.navigateTo / uni.redirectTo / uni.switchTab / uni.navigateBack / uni.reLaunch 上报路由切换 PV | spa: true | | 静态资源测速（手动） | 通过 aegis.reportAsset() 手动上报 | reportAssetSpeed: true | | 设备信息 | uni.getSystemInfoSync | 默认开启 | | AID | uni.setStorageSync 持久化 | 默认开启 |

不支持的能力（架构限制）

| 功能 | 原因 | |------|------| | 静态资源自动测速 | wgt 双线程架构，逻辑层无法感知视图层资源加载 | | FCP / LCP / CLS 等 Web Vitals | 同上，PerformanceObserver 在视图层，SDK 无法访问 | | setData 性能 | uniapp 无 setData 概念 | | 分包加载 | App 端无分包概念 |

日志

Aegis SDK 会主动收集用户的一些性能和错误日志，开发者可以根据不同的参数来配置哪些日志需要上报，以及上报的日志具体信息。

日志类型

常用日志类型如下：

{ logType: 'custom', name: '自定义测速' }
{ logType: 'event', name: '自定义事件' }
{ logType: 'log', name: '日志' }
{ logType: 'speed', name: '接口和静态资源测速' }

日志等级

常用日志等级如下：

{ level: 1, name: '白名单日志' }
{ level: 2, name: '一般日志' }
{ level: 4, name: '错误日志' }
{ level: 8, name: 'Promise 错误' }
{ level: 16, name: 'Ajax 请求异常' }
{ level: 1024, name: 'retcode 异常' }
{ level: 2048, name: 'aegis report' }
{ level: 8192, name: '自定义事件' }
{ level: 32768, name: 'websocket 错误' }

日志上报

创建完 Aegis 实例之后，就可以主动上报日志。

// info 可以上报任意字符串、数字、数组、对象，但是只有打开页面的用户在白名单中才会上报
this.$aegis.info('test');
this.$aegis.info('test', 123, ['a', 'b', 'c', 1], { a: '123' });

// infoAll 表示全量上报
this.$aegis.infoAll({
  msg: 'test',
  ext1: 'ext1',
  ext2: 'ext2',
  ext3: 'ext3',
});

// error 用来表示 JS 错误日志，也是全量上报
this.$aegis.error(new Error('主动上报一个错误'));

// report 可以传入任何日志类型
this.$aegis.report({
  msg: '这是一个 ajax 错误日志',
  level: Aegis.logType.AJAX_ERROR,
  ext1: 'ext1',
  ext2: 'ext2',
  ext3: 'ext3',
});

aid

Aegis SDK 为每个用户设备分配的唯一标识，会存储在 uni 的 storage 中，用来区分用户、计算 UV 等。aid 只有用户清理 App 缓存时才会更新。

实例方法

Aegis 实例暴露以下常用方法：setConfig、info、infoAll、report、error、reportEvent、reportTime、time、timeEnd、destroy、reportAsset、reportPageReady。

setConfig

该方法用来修改实例配置，比如一开始无法获取 uin，可以在获取到用户信息后再设置。

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
});

// 拿到 uin 之后
this.$aegis.setConfig({
  uin: '888',
});

reportEvent

该方法可用来上报自定义事件，平台会统计上报事件的各项指标。

this.$aegis.reportEvent('XXX 请求成功');

this.$aegis.reportEvent({
  name: 'XXX 请求成功',
  ext1: '额外参数1',
  ext2: '额外参数2',
  ext3: '额外参数3',
});

reportTime

该方法可用来上报自定义测速。

this.$aegis.reportTime('customOperation', 1000);

this.$aegis.reportTime({
  name: 'customOperation',
  duration: 1000,
  ext1: 'test1',
  ext2: 'test2',
  ext3: 'test3',
});

time、timeEnd

该方法适用于两个时间点之间时长的计算并上报。

this.$aegis.time('complexOperation');

// 做了很久的复杂操作之后
this.$aegis.timeEnd('complexOperation');

reportAsset

该方法用于手动上报静态资源加载耗时。

:::: warning 注意 ⚠️ 需要在初始化时配置 reportAssetSpeed: true，插件才会挂载 aegis.reportAsset()。 ::::

this.$aegis.reportAsset({
  url: 'https://cdn.xx.com/banner.png',
  duration: 320,
  type: 'image',
  success: true,
});

destroy

该方法用于销毁 SDK 实例，销毁后不再进行数据上报。

this.$aegis.destroy();

白名单

白名单功能适用于开发者希望对某些特定用户上报更多日志，但又不希望全部用户都产生大量上报的场景。

白名单用户会上报全部 API 请求信息，包括接口请求和请求结果。
白名单用户可以使用 info 接口进行信息上报。
infoAll 会对所有用户无差别上报，可能导致日志量较大。
通过 whitelist 接口判断当前用户是否是白名单用户，返回结果会绑定在 Aegis 实例上（aegis.isWhiteList）。
可在应用管理-白名单管理内创建白名单。

错误监控

:::: warning 注意 ⚠️ Aegis 的实例会自动进行以下监控。当您只是引入 SDK 而没有将其实例化时，Aegis 将什么都不会做。 ::::

JS 执行错误

Aegis 会通过 App.onError、uni.onError、Vue errorHandler 等入口获取项目中的报错，并将错误信息自动上报到后台服务中。

Promise 错误

Aegis 会通过 App.onUnhandledRejection、uni.onUnhandledRejection 等入口获取未处理的 Promise 错误。

request 请求异常

Aegis 会改写 uni.request / uni.uploadFile / uni.downloadFile，监听每次接口请求。当 statusCode 不存在、大于等于 400、请求超时或请求失败时，会认为该请求是一个失败请求。

注意：Aegis SDK 在错误发生时默认不会主动收集接口请求参数和返回信息。如果需要上报接口信息，可以开启 api.apiDetail。

new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  api: {
    apiDetail: true,
  },
});

retcode 异常

Aegis 在改写 uni.request 后，将获得 API 返回内容，并尝试在内容中获取本次请求的 retcode。

retcode 的值会从接口返回数据第一层的 code、ret、retcode、errcode 中获取。 Aegis 默认 retcode 的值为 0 是正常的，非 0 都是异常的。用户可以通过 api.retCodeHandler 对这个值和是否异常进行修正。

websocket 异常

Aegis 默认不会对全局 WebSocket 对象进行重写。如果需要打开相关功能，可以在创建 Aegis 对象时设置 websocketHack: true。

new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  websocketHack: true,
});

接口测速

打开方式：初始化时传入配置 reportApiSpeed: true。

Aegis 通过劫持 uni.request / uni.uploadFile / uni.downloadFile 进行接口测速。

页面性能

打开方式：初始化时传入配置 pagePerformance: true，并注册 pagePerformanceMixin。

uniapp App 端没有 wx.getPerformance()，SDK 通过全局 mixin 的 onLaunch、页面 onLoad、onReady 生命周期统计页面性能：

首个页面 onReady：上报 appLaunch，表示 App 业务启动到首屏页面 ready 的耗时。
后续页面 onReady：上报 pageRouteTiming，表示页面 onLoad 到 onReady 的耗时。

Vue 2 接入

import Vue from 'vue';
import Aegis, { pagePerformanceMixin } from 'aegis-uniapp-sdk';

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  pagePerformance: true,
});

Vue.mixin(pagePerformanceMixin);
Vue.prototype.$aegis = aegis;

Vue 3 接入

import { createSSRApp } from 'vue';
import App from './App.vue';
import Aegis, { pagePerformanceMixin } from 'aegis-uniapp-sdk';

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  pagePerformance: true,
});

export function createApp() {
  const app = createSSRApp(App);
  app.mixin(pagePerformanceMixin);
  app.config.globalProperties.$aegis = aegis;
  return { app };
}

默认会在页面 onReady 时上报。如果业务希望在接口、图片或关键模块加载完成后再结束页面性能统计，可以使用手动模式：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  pagePerformance: {
    reportTiming: 'manual',
  },
});

// 关键资源加载完成后调用
this.$aegis.reportPageReady();

// 如需指定页面地址，也可以传 from
this.$aegis.reportPageReady({
  from: 'pages/index/index',
});

::::: warning 注意 ⚠️ pagePerformance 默认关闭。开启后必须同时注册 pagePerformanceMixin，否则 SDK 无法感知页面生命周期，也就无法计算 appLaunch 和 pageRouteTiming。 :::::

页面流转（SPA/PV）

打开方式：初始化时传入配置 spa: true。

开启后，SDK 会拦截以下 uniapp 路由跳转 API，并在跳转成功且页面地址发生变化时自动上报一次 PV：

uni.navigateTo
uni.redirectTo
uni.switchTab
uni.navigateBack
uni.reLaunch

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  spa: true,
});

路由 PV 上报不依赖 pagePerformance，如果只需要页面流转统计，只配置 spa: true 即可。

::::: warning 注意 ⚠️ spa 默认关闭，只上报路由切换 PV。页面首次访问 PV 仍由 SDK 初始化后的默认 PV 流程上报。 :::::

静态资源测速

打开方式：初始化时传入配置 reportAssetSpeed: true。

wgt 运行在逻辑层，SDK 无法自动感知视图层图片、字体、音视频等静态资源加载情况。因此静态资源测速需要业务在资源加载完成或失败时手动上报。

<image
  :src="bannerUrl"
  @load="onBannerLoad"
  @error="onBannerError"
/>

export default {
  data() {
    return { imgStart: 0 };
  },
  onLoad() {
    this.imgStart = Date.now();
  },
  methods: {
    onBannerLoad() {
      this.$aegis.reportAsset({
        url: this.bannerUrl,
        duration: Date.now() - this.imgStart,
        type: 'image',
        success: true,
      });
    },
    onBannerError() {
      this.$aegis.reportAsset({
        url: this.bannerUrl,
        duration: Date.now() - this.imgStart,
        type: 'image',
        success: false,
      });
    },
  },
};

配置文档

| 配置 | 描述 | |------|------| | id | 必须，string，默认无。开发者平台分配的项目上报 ID | | uin | 建议，string。业务定义的当前用户唯一标识，用来查找固定用户的日志 | | onError | 可选，boolean 或 object，默认 true。是否开启错误监听 | | device | 可选，boolean，默认 true。是否采集设备信息 | | aid | 可选，boolean 或 string，默认 true。是否生成并上报设备唯一标识 | | reportApiSpeed | 可选，boolean，默认 false。是否开启接口测速和请求异常监控 | | reportAssetSpeed | 可选，boolean，默认 false。是否开启手动静态资源测速 | | pagePerformance | 可选，boolean 或 object，默认 false。是否开启页面性能统计；传 { reportTiming: 'manual' } 时需手动调用 reportPageReady() 结束统计 | | spa | 可选，boolean，默认 false。是否开启路由切换 PV 自动上报 | | websocketHack | 可选，boolean，默认 false。是否开启 WebSocket 异常监控 | | version | 可选，string，默认 SDK 版本号。当前上报版本 | | delay | 可选，number，默认 1000 ms。上报节流时间 | | repeat | 可选，number，默认 60。重复上报次数，对于同一个错误或者同一个接口测速超过多少次不上报 | | env | 可选，enum，默认 Aegis.environment.production。当前项目运行所处的环境 | | pageUrl | 可选，string。修改上报数据中的页面地址 | | urlHandler | 可选，Function。动态修改上报数据中的页面地址 from，可以配合 pageUrl 参数使用 | | hostUrl | 可选，默认 https://rumt-zh.com。影响全部上报数据的 host 地址 | | url | 可选，string，默认 https://rumt-zh.com/collect。日志上报地址 | | whiteListUrl | 可选，string，默认 https://rumt-zh.com/collect/whitelist。白名单确认接口。如果想关闭白名单接口请求，可以传空字符串 | | offlineUrl | 可选，string，默认 https://rumt-zh.com/collect/offline。离线日志上报地址 | | eventUrl | 可选，string，默认 https://rumt-zh.com/collect/events。自定义事件上报地址 | | speedUrl | 可选，string，默认 https://rumt-zh.com/speed。测速日志上报地址 | | customTimeUrl | 可选，string，默认 https://rumt-zh.com/speed/custom。自定义测速上报地址 | | beforeRequest | 可选，Function。日志上报前执行，用于拦截或修改上报数据 | | afterRequest | 可选，Function。日志上报后执行 | | onBeforeRequest | 可选，Function。上报请求发出前执行，用于修改请求参数 | | beforeReport | 可选，Function。普通日志上报前执行，返回 false 可以阻止上报 | | beforeReportSpeed | 可选，Function。测速日志上报前执行，返回 false 可以阻止上报 | | api | 可选，object，默认为 {}。接口测速和 retcode 相关配置 | | ext1 | 可选，string，自定义上报的额外维度 | | ext2 | 可选，string，自定义上报的额外维度 | | ext3 | 可选，string，自定义上报的额外维度 |

api 配置示例

假如后台返回数据为：

{
  "body": {
    "code": 200,
    "retCode": 0,
    "data": {}
  }
}

业务需要 code 不为 200，或者 retCode 不为 0 时认为此次请求异常。此时只需进行以下配置：

new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  api: {
    retCodeHandler(data) {
      try {
        data = JSON.parse(data);
      } catch (e) {}
      return {
        isErr: data.body.code !== 200 || data.body.retCode !== 0,
        code: data.body.code,
      };
    },
  },
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

aegis-uniapp-sdk

使用

安装

初始化

Vue 2（main.js）

Vue 3（main.js）

支持的监控能力

不支持的能力（架构限制）

日志

日志类型

日志等级

日志上报

aid

实例方法

setConfig

reportEvent

reportTime

time、timeEnd

reportAsset

destroy

白名单

错误监控

JS 执行错误

Promise 错误

request 请求异常

retcode 异常

websocket 异常

接口测速

页面性能

Vue 2 接入

Vue 3 接入

页面流转（SPA/PV）

静态资源测速

配置文档

api 配置示例