应用实时监控服务ARMS：SDK配置参考

启动配置

start方法是AlibabaCloudRUM Flutter 插件的核心启动方法，负责初始化整个 Flutter 插件监控系统并启动应用程序。

Future<void> start(Widget topLevelWidget, {Function()? beforeRunApp}) async

示例：

AlibabaCloudRUM().start(
  // 根 Widget
  MyApp(),
  beforeRunApp: () async => {
    // 在当前函数结束前，必须要调用下面这个方法
    WidgetsFlutterBinding.ensureInitialized(),
    // 其他业务逻辑
    // ...
    },
);

启动配置（高级）

除了start方法之外，您还可以通过initialize方法启动SDK。通过这种方式启动SDK时，您需要在initialize方法之前调用WidgetsFlutterBinding.ensureInitialized。

Future<void> initialize();

示例：

// 确保在调用`initialize`之前调用`WidgetsFlutterBinding.ensureInitialized`
WidgetsFlutterBinding.ensureInitialized();
// 调用`initialize`方法完成SDK初始化
AlibabaCloudRUM().initialize();
// 记得调用`runApp`
runApp(MyApp());

打印错误信息

当SDK捕获到Flutter异常时，会默认调用FlutterError.dumpErrorToConsole输出错误信息到控制台，您可以通过setDumpError方法开启或关闭。

void setDumpError(bool enable)

示例：

// 禁止输出错误信息到控制台
AlibabaCloudRUM().setDumpError(false);  

Flutter错误回调

由于Flutter对错误的监控无法逐层传递，导致AlibabaCloudRUM插件对同步、异步接口进行监控后，应用内原有的错误监听会失效。因此，Flutter插件提供了统一的错误回调接口。

void onRUMErrorCallback(bool callback(Object? error, StackTrace? stack, bool isAsync))

回调函数入参：

回调函数返回值：

示例：

  AlibabaCloudRUM().onRUMErrorCallback((error, stack, isAsync) {
    // 处理error事件
    // ...
    // logger.d('debuggg error: $error, stack: $stack');

    // 返回true，让SDK上报该错误
    return true;
  });

读取设备Id

SDK会默认生成一个deviceId，您可以通过getDeviceId接口读取设备Id。

Future<String?> getDeviceId() async

示例：

AlibabaCloudRUM().getDeviceId().then(((value) => {print("deviceId: ${value}")}));

自定义用户名称

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

Future<void> setUserName(String userName)

示例：

AlibabaCloudRUM().setUserName("xxxxx");

自定义用户扩展信息

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

• 设置用户扩展信息，为覆写模式，调用该方法会导致历史设置的用户扩展信息被覆盖。

  Future<void> setUserExtraInfo(Map<String, dynamic> extraInfo) async

  参数	说明	参数限制	失败结果
  extraInfo	用户扩展信息	Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。	接口调用失败，当次设置无效

  示例：

  AlibabaCloudRUM().setUserExtraInfo({"shopId": "xxxxx", "shopName": "yyyyy"});

• 追加用户扩展信息，追加模式。

  Future<void> addUserExtraInfo(Map<String, dynamic> extraInfo) async

  参数	说明	参数限制	失败结果
  extraInfo	用户扩展信息	Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。	接口调用失败，当次设置无效

  示例：

  AlibabaCloudRUM().addUserExtraInfo({"userId": "11111111"});

自定义全局扩展信息

SDK支持设置全局扩展信息，该信息会附加到所有上报数据中，便于您在数据分析时按全局维度进行筛选和关联。

• 设置全局扩展信息，为覆写模式，调用该方法会导致历史设置的用户扩展信息被覆盖。

  Future<void> setExtraInfo(Map<String, dynamic> extraInfo) async

  参数	说明	参数限制	失败结果
  extraInfo	全局扩展信息	Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。	接口调用失败，当次设置无效

  示例：

  AlibabaCloudRUM().setExtraInfo({"global_key": "global_value", "global_key2": "global_value2"});

• 追加全局扩展信息，追加模式。

  Future<void> addExtraInfo(Map<String, dynamic> extraInfo) async

  参数	说明	参数限制	失败结果
  extraInfo	全局扩展信息	Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。	接口调用失败，当次设置无效

  示例：

  AlibabaCloudRUM().addExtraInfo({"global_userId": "2222222222"});

自定义异常

调用自定义异常接口，并传入相应的参数，可完成自定义异常数据的统计功能。

Future<void> setCustomException(String exceptionType, String causedBy, String errorDump)

示例：

AlibabaCloudRUM().setCustomException("custom exception type", 
    "caused by customer", 
    "Custom error dump");

自定义事件

SDK支持上报自定义事件。调用相应的接口，并传入相应的参数，可完成自定义事件数据的统计功能。

Future<void> setCustomEvent(String name, {String? group, String? snapshots, double? value, Map<String, String>? attributes})

示例：

AlibabaCloudRUM().setCustomEvent("search_shop",
    group: "shop",
    snapshots: 'Search: ${search.toString()}',
    value: 1,
    attributes: {"search": "xxxxx"});

自定义日志

SDK支持上报自定义日志信息。调用相应的接口，并传入相应的参数，可完成自定义日志数据的统计功能。

Future<void> setCustomLog(String logInfo, {String? name, String? snapshots, String? level, Map<String, String>? attributes})

示例：

AlibabaCloudRUM().setCustomLog("2024-08-20 14:00:05 Print shopinfo info.",
    name: "shop",
    snapshots: 'Shop: ${shop.toString()}',
    level: "DEBUG",
    attributes: {"shopId": "xxxxx", "shopName": "yyyyy"});

资源快照采集

SDK支持采集应用的资源快照数据，帮助您了解应用的资源使用情况。

void startResourceSnapshot()
void stopResourceSnapshot()

示例：

// 开始采集资源快照
AlibabaCloudRUM().startResourceSnapshot();
// 停止采集资源快照
AlibabaCloudRUM().stopResourceSnapshot();

HttpClient

SDK支持对dart:io中的HttpClient进行监控，自动采集HTTP请求的性能数据。

使用AlibabaCloudRUMHttpClient替代原生HttpClient即可实现监控。

示例：

import 'package:alibaba_cloud_rum/alibaba_cloud_rum_http_client.dart';

// 使用 AlibabaCloudRUMHttpClient 替代原生 HttpClient
final client = AlibabaCloudRUMHttpClient();
final request = await client.getUrl(Uri.parse('https://example.com/api'));
final resp = await request.close();
print('Response status: ${resp.statusCode}');

Dio

SDK支持对Dio HTTP客户端进行监控。Dio是Flutter生态中广泛使用的HTTP库，通过集成SDK提供的拦截器，可以自动采集HTTP请求的性能数据。

使用AlibabaCloudRUMInterceptor拦截器集成监控功能。

示例：

import 'package:dio/dio.dart';
import 'package:alibaba_cloud_rum/alibaba_cloud_rum_interceptor.dart';

final dio = Dio();
// 添加 AlibabaCloudRUM 拦截器
dio.interceptors.add(AlibabaCloudRUMInterceptor());

// 正常使用 Dio 发送请求
final resp = await dio.get('https://example.com/api');
print('Response: ${resp.data}');

注意事项

使用SDK时，请注意以下事项：

• 版本兼容性：SDK支持Flutter 3.0及以上版本。如果您的应用使用较低版本的Flutter，请先升级Flutter版本。

• 网络权限：请确保应用已获取网络访问权限，否则SDK无法正常上报数据。

• 数据量控制：SDK默认会控制数据上报频率，避免对应用性能造成影响。如果需要调整上报策略，请联系技术支持。

• 隐私合规：SDK采集的数据仅用于应用性能监控和分析，不会采集用户敏感信息。请在隐私政策中告知用户应用集成了性能监控功能。

• 初始化时机：建议在应用启动时尽早初始化SDK，以确保能够采集到完整的性能数据。