aegis_flutter_sdk 0.0.2
aegis_flutter_sdk: ^0.0.2 copied to clipboard

flutter aegis-sdk - a part of tencent monitor platform (https://console.cloud.tencent.com/rum)

aegis_flutter_sdk #

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

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

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

Usage #

  1. 前往腾讯云前端性能监控 RUM 平台

  2. 申请项目,申请完成后得到上报 id,id 在 sdk 初始化的时候会使用。

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

支持的特性 #

FeatureAndroidiOSWeb
普通日志上报
错误日志上报
白名单日志上报
自定义事件上报
自定义测速
页面加载速度自动测速
离线日志
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方法”
aegis.info(
    '我是一条白名单上报的信息,只有在白名单中的用户才会上报哟。你可以在开发者平台把老板、产品、测试统统都加进白名单中。'
);
/// aegis.infoAll支持任意类型的参数,包括map, list, string, int等。 如果是object对象,务必提供“toJson方法”
aegis.infoAll(
    '我是一条普通的信息,如果上报量很大的话请谨慎使用哟。'
);
/// aegis.report支持任意类型的参数,包括map, list, string, int等。 如果是object对象,务必提供“toJson方法”
aegis.report(
    'error'
)

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 实例有以下方法供您使用:
setConfiginfoinfoAllreporterrorreportEventreportTimetimetimeEnd

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');

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 设定了白名单的逻辑。

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

页面加载耗时上报 #

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

  1. runApp 之前先初始化 Aegis ,并将 configenablePageLoadTime 设置为 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 {
  });
}
  1. MaterialApp 中添加 navigatorObservers ,初始化 TAMPageNavigatorObserver()
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Demo(),
      navigatorObservers: [PageNavigatorObserver()],
    );
  }
}
  1. 启动页面由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/aegis/whitelist'。
白名单确认接口
如果想要关闭白名单接口请求,可以传空字符串
ext1可选,string,自定义上报的额外维度,上报的时候可以被覆盖
ext2可选,string,自定义上报的额外维度,上报的时候可以被覆盖
ext3可选,string,自定义上报的额外维度,上报的时候可以被覆盖

<br/>

2
likes
110
pub points
28%
popularity

flutter aegis-sdk - a part of tencent monitor platform (https://console.cloud.tencent.com/rum)

Homepage

Documentation

API reference

License

MIT (LICENSE)

Dependencies

eventify, flutter, http, shared_preferences, stack_trace, universal_html

More

Packages that depend on aegis_flutter_sdk