Alibaba Cloud RUM SDK for Flutter

package	pub	likes	popularity	pub points
alibabacloud_rum_flutter_plugin

阿里云用户体验监控 RUM 官方 Flutter 插件，当前支持 Android、iOS、HarmonyOS 平台。

插件集成

1. 添加依赖

dependencies:
  flutter:
    sdk: flutter

  alibabacloud_rum_flutter_plugin: ^2.3.7

2. 在Flutter项目根目录执行以下命令

flutter packages get

3. iOS 在工程 ios 目录下执行以下命令

pod install

4. 初始化 SDK

在 main.dart 文件中导入以下包：

import 'package:alibabacloud_rum_flutter_plugin/alibabacloud_rum_flutter_plugin.dart';

完成 SDK 的初始化：

void main() {
  // 注释原有的 runApp() ⽅法
  // runApp(MyApp());
  // （必须）初始化SDK
  AlibabaCloudRUM().start(MyApp());
  // （可选）自定义用户名称
  AlibabaCloudRUM().setUserName("xxxxxx");
}

错误采集按 Flutter 引擎能力安装：支持 PlatformDispatcher.onError 时保留该入口；Flutter 3.0.0 等缺少该成员的旧引擎仅略过此入口，不影响 FlutterError.onError、HTTP 监控或配置初始化。start() 启动的应用继续由 SDK 管理的 Zone 捕获其范围内的未处理异常，但无法保证覆盖该 Zone 之外的异步异常。

若使用 initialize() 后手动调用 runApp()，后续应用代码不会自动进入 SDK 管理的 Zone；需要由应用自行管理 Zone。旧引擎的异常覆盖范围因此与新引擎不同，Dart Self Monitor 也遵守相同边界。

5. 接入验证

Flutter 应用启动后，DEBUG CONSOLE 中返回 [INFO][AlibabaCloudRUM]: alibabacloud_rum_flutter_plugin initialized successfully 即表示 SDK 接入成功。示例如下：

flutter: [2024-05-27 16:43:39][INFO][AlibabaCloudRUM]: alibabacloud_rum_flutter_plugin initialized successfully

Flutter SDK 日志控制

通过 AlibabaCloudRUM().setDebuggable(bool debuggable) 控制 Flutter/Dart 层的详细诊断日志，默认值为 false：

debuggable	verbose	debug	info	warn	error
true	打印	打印	打印	打印	打印
false（默认）	不打印	不打印	打印	打印	打印

final rum = AlibabaCloudRUM();
rum.setDebuggable(true); // 开启所有级别的 Flutter SDK 日志
await rum.start(MyApp());

rum.setDebuggable(false); // 恢复仅打印 info/warn/error

该接口同步生效，可以在 start() / initialize() 前调用，也可以在运行时反复切换；重复初始化不会重置已设置的值。Debug、Profile、Release 构建遵守相同规则。升级后默认不再输出 verbose/debug；排查问题需要详细日志时，请显式调用 setDebuggable(true)。

正常逐请求、逐页面的事件、模型和指标使用 debug/verbose；少量启动及功能状态使用 info，参数校验和局部降级使用 warn，操作失败及其错误堆栈使用 error。

此开关仅控制 Flutter/Dart 层的 SDK 诊断日志，不向 Native 下发配置。setDumpError 仍独立控制额外错误 dump；RUM 采集上报、setCustomLog 业务日志上报和 Dart Self Monitor 均不受此开关影响。

Action 自动采集

在应用根 Widget 中使用 AlibabaCloudActionCapture 包裹 MaterialApp：

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return AlibabaCloudActionCapture(
      child: MaterialApp(
        home: const HomePage(),
      ),
    );
  }
}

如果需要为指定 Widget 设置稳定的 Action 描述和自定义属性，使用 ActionAnnotation：

ActionAnnotation(
  description: '提交订单',
  attributes: const {
    'page': 'checkout',
    'business_action': 'submit_order',
  },
  child: ElevatedButton(
    onPressed: submitOrder,
    child: const Text('提交'),
  ),
)

description 会优先于 Widget 子树中的 Text 或 Semantics 文案。attributes 的值必须可被 jsonEncode 编码，且不应包含密码、Token 或个人信息等敏感数据。

Dart Self Monitor

Self Monitor 只采集进入既有统一异常回调、且可高置信度归因到插件自有代码的 Dart 异常，复用 Native SDK 的 /rum/monitor 通道。App、用户 callback 和 Flutter framework 异常不镜像到该通道；已被内部捕获并吞掉的异常不在采集范围内。

// 默认开启。仅控制 Dart 采集，不修改 Native Self Monitor 开关。
AlibabaCloudRUM().setSelfMonitorEnabled(false);

使用 Dart Self Monitor 时，需要同时集成提供 Self Monitor Integration API 的配套原生 SDK，并在宿主中完成原生 SDK 初始化。

Self Monitor 不提供业务自定义日志/metric 上报 API。内部提交成功只表示 Native producer 已接管，不保证网络送达；上下文按事件时 Native 已生效的 session/view 绑定，无法确认时不回退到当前页面。

Self Monitor Bridge 的 log 只允许 level、type、content 和可选 stack，禁止 attributes（包括空对象和 null），携带该字段返回 rejected/invalid_payload。Dart 的 SHA-256 fingerprint 仅用于内部去重，不上传，也不改名写入其它字段。timestamp 是事件产生时的 epoch 毫秒值，编码和发送保留该值。业务 RUM 的属性及 Native 已有的顶层 crash evidence、iOS metric 行为保持原有契约。

Native SDK 集成

Flutter 项目在集成 Alibaba Cloud RUM SDK 时，除了需要集成 Flutter 插件之外，还需要分别集成 Android、iOS SDK。您可以参考下面的文档集成：

• Android：接入Android应用
• iOS：接入iOS应用

Flutter API 说明

API	说明
start	启动Flutter插件
setDebuggable	开关 Flutter SDK 详细日志；默认关闭，保留 info/warn/error
setUserName	设置用户名称
setCustomEvent	设置自定义事件
setCustomException	设置自定义异常
setSelfMonitorEnabled	控制 Dart Self Monitor 采集；默认开启，需配套原生 SDK
AlibabaCloudActionCapture	自动采集 Flutter 用户操作
ActionAnnotation	为操作设置自定义描述和属性
GestureCaptureInfo	描述自定义 Widget 的采集方式
CustomGestureElementCapture	自定义 Widget 识别回调