aegis_flutter_sdk

项目介绍

Aegis（读音/ˈiːdʒɪs/）是腾讯云监控团队提供的前端监控 SDK，涵盖了错误监控，资源测速（img, script, css），接口测速，页面性能（首屏时间）。无需侵入代码，只需引入 SDK 即可自动完成所有监控上报。

在使用 aegis 时无需在业务代码中打点或者做任何其他操作，可以做到与业务代码充分解耦。aegis 将会自动监控前端错误，在错误发生时上报错误的具体情况，帮助您快速定位问题。当您开启资源测速时，aegis 将会自动监听页面资源加载情况（耗费时长、成功率等），并在不影响前端性能的前提下收集前端的性能数据，帮助您快速定位性能短板，提升用户体验。

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

快速上手

前往腾讯云前端性能监控 RUM 平台
申请项目，申请完成后得到上报 id，id 在 sdk 初始化的时候会使用。

Aegis SDK 在上报所有数据时都会带上上报 id，后端服务将根据上报 id辨别数据来自哪一个项目，因此，Aegis 建议为每一个项目都单独申请一个 id，如果一个项目下有多个页面，还可以为每一个页面都申请一个项目 id，方便单独查看每一个页面的 PV、错误率、请求错误率等数据。

支持的特性

Feature	Android	iOS	Web
普通日志上报	✅	✅	✅
错误日志上报	✅	✅	✅
白名单日志上报	✅	✅	✅
自定义事件上报	✅	✅	✅
自定义测速	✅	✅	✅
页面加载速度自动测速	✅	✅	✅
离线日志
Http接口测速
钩子函数

发布

运行 dry-run 命令以查看是否都准备OK了运行 publish 命令正式发布

flutter packages pub publish --dry-run
flutter packages pub publish

使用SDK

依赖引入

在flutter sdk项目中加入依赖：

dependencies:
  ...
  aegis_flutter_sdk:

初始化实例

import 'package:aegis_flutter_sdk/aegis_flutter_sdk.dart'　

final aegis = Aegis(
  Config(
    id: 'xxxxx',
    uin: 'xxxxx',
  ),
);

日志上报

创建完 Aegis 实例之后，就可以开心的上报日志啦 🥰，日志上报同样简单

/// aegis.info支持任意类型的参数，包括map, list, string, int等。 如果是object对象，务必提供“toJson方法”
/// 同时可以指定ext1/ext2/ext3（一个或多个）特定参数
aegis.info(
    '我是一条白名单上报的信息，只有在白名单中的用户才会上报哟。你可以在开发者平台把老板、产品、测试统统都加进白名单中。'
);
aegis.info(
    '我是一条白名单上报的信息，只有在白名单中的用户才会上报哟。你可以在开发者平台把老板、产品、测试统统都加进白名单中。',
    ext1: 'xxx',
    ext1: 'xxx',
    ext1: 'xxx'
);
/// aegis.infoAll支持任意类型的参数，包括map, list, string, int等。 如果是object对象，务必提供“toJson方法”
/// 同时可以指定ext1/ext2/ext3（一个或多个）特定参数
aegis.infoAll(
    '我是一条普通的信息，如果上报量很大的话请谨慎使用哟。'
);
aegis.infoAll(
    '我是一条普通的信息，如果上报量很大的话请谨慎使用哟。',
    ext1: 'xxx',
    ext1: 'xxx',
    ext1: 'xxx'
);
/// aegis.report支持任意类型的参数，包括map, list, string, int等。 如果是object对象，务必提供“toJson方法”
/// 同时可以指定ext1/ext2/ext3（一个或多个）特定参数
aegis.report(
    'error'
)
aegis.report(
    'error',
    ext1: 'xxx',
    ext1: 'xxx',
    ext1: 'xxx'
)

aid

Aegis SDK 为每个用户设备分配的唯一标示，会存储在客户端里，用来区分用户，计算 uv 等。aid只有用户删除app才会更新。

算法如下:

void setAid() async {
  SharedPreferences prefs = await SharedPreferences.getInstance();
  String? aid = prefs.getString('AEGIS_ID');
  if (aid != null) {
    bean['aid'] = aid;
    config.setAid(aid);
  } else {
    aid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
        .replaceAllMapped(RegExp(r"[xy]"), (match) {
      int r = Random().nextInt(16);
      int v = match[0] == 'x' ? r : (r & 0x3) | 0x8;
      return v.toRadixString(16);
    });
    prefs.setString('AEGIS_ID', aid);
    bean['aid'] = aid;
    config.setAid(aid);
  }
}

实例方法

Aegis 实例暴露接口简单实用，目前 Aegis 实例有以下方法供您使用：
setConfig 、 info 、 infoAll 、 report 、 error 、 reportEvent 、 reportTime 、 time 、 timeEnd

setConfig

该方法用来修改实例配置，比如下面场景：
在实例化 Aegis 时需要传入配置对象

import 'package:aegis_flutter_sdk/aegis_flutter_sdk.dart'

final aegis = Aegis(
  Config(
    id: 'xxxxx',
    uin: 'xxxxx',
  ),
);

很多情况下，并不能一开始就获取到用户的 uin，而等获取到用户的 uin 才开始实例化 Aegis，如果这期间发生了错误 Aegis 将监听不到。uin 的设置可以在获取到用户的时候：

final aegis = Aegis(
  Config(
    id: 'xxxxx',
    uin: 'xxxxx',
  ),
);
// 拿到uin之后...
aegis.setConfig({
    uin: 'yyyyyyy'
})

setConfig支持传入的参数包括uin,aid,version,ext1,ext2,ext3

info、infoAll、report

这三个方法是 Aegis 提供的主要上报手段。

aegis.info('上报一条白名单日志，这两种情况这条日志才会报到后台：1、打开页面的用户在名单中；2、对应的页面发生了错误🤨');

aegis.infoAll('上报了一条日志，该上报与info唯一的不同就在于，所有用户都会上报');

aegis.report('error');

如上接口均可添加可选参数ext1/ext2/ext3指定具体的扩展参数

reportEvent

该方法可用来上报自定义事件，平台将会自动统计上报事件的各项指标，诸如：PV、UV、平台分布等...

reportEvent目前只支持字符串类型上报

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

reportTime

该方法可用来上报自定义测速，例如：

// 假如‘onload’的时间是1s
 aegis.reportTime('onLoad', 1000);

或者如果需要使用额外参数，可以传入对象类型参数，ext1，ext2，ext3 会覆盖默认值：

aegis.reportTime('onLoad', 1000,
  ext1: 'ext1', ext2: 'ext2', ext3: 'ext3', from: '');

onload 可以修改为其他的命名。

time、timeEnd

该方法同样可用来上报自定义测速，适用于两个时间点之间时长的计算并上报，例如：

aegis.time('complexOperation');
/**
 * .
 * .
 * 做了很久的复杂操作之后。。。
 * .
 * .
 */
aegis.timeEnd('complexOperation'); /** 此时日志已经报上去了😄**/

complexOperation 同样可以修改为其他的命名。自定义测速是用户上报任意值，服务端对其进行统计和计算，因为服务端不能做脏数据处理，因此建议用户在上报端进行统计值限制，防止脏数据对整体产生影响。目前 Aegis 只支持 0-60000 的数值计算，如果大于该值，建议进行合理改造。

白名单

白名单功能是适用于开发者希望对某些特定的用户上报更多的日志，但是又不希望太多上报来影响到全部日志数据，并且减少用户的接口请求次数，因为 TAM 设定了白名单的逻辑。

白名单用户会上报全部的 API 请求信息，包括接口请求和请求结果。
白名单用户可以使用 info 接口信息数据上报。
info vs infoAll：在开发者实际体验过程中，白名单用户可以添加更多的日志，并且使用 info 进行上报。infoAll 会对所有用户无差别进行上报，因此可能导致日志量上报巨大。
通过接口 whitelist 来判断当前用户是否是白名单用户，白名单用户的返回结果会绑定在 aegis 实例上 (aegis.isWhiteList) 用来给开发者使用。
用了减少开发者使用负担，白名单用户是团队有效，可以在组织管理-白名单管理内创建白名单，则团队下全部项目都生效。

页面加载耗时上报

页面加载耗时上报需按如下步骤：

runApp 之前先初始化 Aegis ，并将 config 的 enablePageLoadTime 设置为 true

void main() {
  runZonedGuarded(() async {
    WidgetsFlutterBinding.ensureInitialized();
    // 先初始化 Aegis 组件，因为需要计算页面渲染时间
    final aegis = Aegis(
      Config(
        id: 'xxxxx',
        uin: 'xxxxx',
        enablePageLoadTime: true,
      ),
    );

    runApp(MyApp());
  }, (Object error, StackTrace stack) async {
  });
}

在 MaterialApp 中添加 navigatorObservers ，初始化 TAM 的 PageNavigatorObserver()

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Demo(),
      navigatorObservers: [PageNavigatorObserver()],
    );
  }
}

启动页面由SDK内部命名为了 firstPage ，后续其他页面的命名建议在初始化 router 时进行设置，SDK默认上报为unknown

    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (BuildContext context) {
          return ChangeNotifierProvider<Catalog>(
            create: (context) => Catalog(),
            child: InfiniteListPage(),
          );
        },
        settings: RouteSettings(name: 'InfiniteListPage'),
      ),
    );

页面命名暂时无法在系统回调处获取 widget名称，所以需要由业务方在 RouteSettings 中设置。待后续优化自动获取 widget 名称作为 page 名称

开启页面加载耗时计算后，页面PV数据在 RUM 平台的 "自定义数据" 中查看

钩子函数/错误监控/离线日志

建设中

配置文档

配置	描述
id	必须，string，默认无。开发者平台分配的项目key
uin	建议，string。当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持`字母数字@=._-`，正则表达式: `/^[@=.0-9a-zA-Z_-]{1,60}$/`
version	可选，string，默认 sdk 版本号。当前上报版本，当页面使用了pwa或者存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持`字母数字.,:_-`，长度在 60 位以内 `/^[0-9a-zA-Z.,:_-]{1,60}$/`
delay	可选，int，默认 1000 ms。上报节流时间，在该时间段内的上报将会合并到一个上报请求中。
repeat	可选，int，默认 5。重复上报次数，对于同一个错误超过多少次不上报。
url	可选，string，默认 '//aegis.qq.com/collect'。日志上报地址
speedUrl	可选，string，默认 '//aegis.qq.com/speed'。测速日志上报地址
whiteListUrl	可选，string，默认 '//aegis.qq.com/collect/whitelist'。白名单确认接口如果想要关闭白名单接口请求，可以传空字符串
ext1	可选，string，自定义上报的额外维度，上报的时候可以被覆盖
ext2	可选，string，自定义上报的额外维度，上报的时候可以被覆盖
ext3	可选，string，自定义上报的额外维度，上报的时候可以被覆盖

常见问题（FAQ）

接口请求报错 403 要怎么处理？

接口403一般是因为页面域名校验失败导致的，可以检查项目创建时候设置的域名跟实际上报的域名是否一致。如果项目刚刚创建或者修改域名校验，TAM数据同步需要一定的时间，大概在1-2min，可以稍微等一下，这段时间用来读一下文档也是不错的。

RUM 自定义测速为什么仅支持 0 - 60000 之间的数据？

之前自定义测速的逻辑是用户上报任意数据，我们对用户数据进行求均值和中位数，然后显示计算后的结果，但是这样带来的问题就是，服务端无法判断脏数据，但是少量脏数据对用户实际数据却会产生非常大的影响，因此我们目前在服务端对用户数据进行了限制，目前只支持 0-60000 内的数据。

RUM 根据哪个字段来计算UV？

aegis sdk 没有根据用户设置的uin来计算uv，因为如果当前用户没有登录，则无法计算，而且uin值由开发者设置，并不完全可靠，还有无法将用户登录前后状态统一起来，因此 aegis sdk 为每个用户独立生成一个 aid 作为用户（设备）的唯一标识，并且存储在 localstorage 里面，不受登录态影响