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支持采集HTTP请求/响应的headers 和 payload 信息。SDK 默认不采集任何资源的快照数据，您需要通过下文中提供的API显示启用。需要通过设置ResourceSnapshotProvider显示启用HttpClient库的快照信息采集。

HttpClient

需要通过设置ResourceSnapshotProvider显示启用HttpClient库的快照信息采集。

void setResourceSnapshotProvider(ResourceSnapshotProvider? provider)

ResourceSnapshotUtils 工具类

由于 HttpClientRequest 是只写流、HttpClientResponse 是只读流，需要使用工具类进行缓存。

示例：

AlibabaCloudRUM().setResourceSnapshotProvider(
  ResourceSnapshotProvider(
    onRequestHeaders: (request) {
      return {
        'content-type': request.headers.value('content-type') ?? '',
      };
    },
    onRequestPayload: (request) {
      // 由于 request 中没有保存 payload 相关的接口，因此，您需要通过 ResourceSnapshotUtils 类，
      // 在请求发起时主动调用 ResourceSnapshotUtils.cacheRequestBody 方法完成 payload 数据的缓存
      final body = ResourceSnapshotUtils.getCachedRequestBody(request);
      if (body == null) return null;
      // 注意，数据需做脱敏处理
      return body.replaceAll(RegExp(r'"password":\s*"[^"]*"'), '"password":"***"');
    },
    onResponsePayload: (response) {
      // 当前暂不支持 response payload 数据的采集
      return null;
    },
  ),
);

AlibabaCloudRUMDioInterceptor({DioResourceSnapshotProvider? onProvideSnapshots})

final dio = Dio();
// 增加 AlibabaCloudRUMDioInterceptor
dio.interceptors.add(
  AlibabaCloudRUMDioInterceptor(
    onProvideSnapshots: (requestOptions, response, error) {
      // 以下仅为示例代码，需要根据业务情况对数据做脱敏处理
      final headers = <String, Object>{};
      response?.headers.forEach((name, value) {
        headers[name] = value;
      });
      return ResourceSnapshots(
        requestHeaders: {...requestOptions.headers},
        requestPayload: requestOptions.data,
        responseHeaders: {...headers},
        responsePayload: jsonEncode(response?.data),
      );
    },
  ),
);
// 省略其他代码

注意事项

• SDK 默认不采集任何 headers/palyload 数据，必须通过上述API显示启用。

• SDK 调用者负责数据脱敏，SDK 不会自动过滤任何敏感信息（包括但不限于：密码、用户个人信息等）。