Application Real-Time Monitoring Service:SDK configuration reference

Startup configuration

The start method is the primary method for the AlibabaCloudRUM Flutter plugin. It initializes the monitoring system and begins monitoring the application.

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

Example:

AlibabaCloudRUM().start(
  // The root widget
  MyApp(),
  beforeRunApp: () async => {
    // You must call the following method before this function ends.
    WidgetsFlutterBinding.ensureInitialized(),
    // Other business logic
    // ...
    },
);

Print error messages

By default, when the SDK catches a Flutter exception, it calls FlutterError.dumpErrorToConsole to print the error message to the console. You can use the setDumpError method to enable or disable this feature.

void setDumpError(bool enable)

Example:

// Disable printing error messages to the console.
AlibabaCloudRUM().setDumpError(false);  

Flutter error callback

Because error monitoring in Flutter is not propagated through layers, the application's original error listener stops functioning after the AlibabaCloudRUM plugin starts monitoring synchronous and asynchronous interfaces. To address this issue, the Flutter plugin provides a unified error callback interface.

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

Callback function input parameters:

Callback function return value:

Example:

  AlibabaCloudRUM().onRUMErrorCallback((error, stack, isAsync) {
    // Process the error event.
    // ...
    // logger.d('debuggg error: $error, stack: $stack');

    // Return true to let the SDK report the error.
    return true;
  });

Read device ID

By default, the SDK generates a `deviceId`. You can use the getDeviceId interface to retrieve this device ID.

Future<String?> getDeviceId() async

Example:

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

Custom username

The SDK lets you set user-related information. This helps you associate data analytics with actual users.

Future<void> setUserName(String userName)

Example:

AlibabaCloudRUM().setUserName("xxxxx");

Custom user extension information

The SDK lets you set user-related information. This helps you associate data analytics with actual users.

• You can set user extension information in overwrite mode. Calling this method overwrites any previously set user extension information.

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

  Parameter	Description	Restrictions	Result if failed
  extraInfo	The user extension information.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the API call fails.	The API call fails. The setting for this call is invalid.

  Example:

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

• You can append user extension information.

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

  Parameter	Description	Restrictions	Result if failed
  extraInfo	The user extension information.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the API call fails.	The API call fails. The setting for this call is invalid.

  Example:

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

Custom global extension information

The SDK lets you set global extension information to associate data analytics with specific scenarios.

• This method sets the global extension information by overwriting any previously set global extension information.

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

  Parameter	Description	Restrictions	Result if failed
  extraInfo	The global extension information.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the API call fails.	The API call fails. The setting for this call is invalid.

  Example:

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

• You can append global extension information.

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

  Parameter	Description	Restrictions	Result if failed
  extraInfo	The global extension information.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the API call fails.	The API call fails. The setting for this call is invalid.

  Example:

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

Custom Exception

You can call the custom exception interface and pass the required parameters to collect data on custom exceptions.

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

Example:

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

Custom events

The SDK supports reporting custom events. You can call the relevant interface and pass the required parameters to collect data on custom events.

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

Example:

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

Custom logs

The SDK supports reporting custom log information. You can call the relevant interface and pass the required parameters to collect custom log data.

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

Example:

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