SDK Initialization¶

This document describes Flutter SDK initialization and related runtime capabilities.

Basic Configuration¶

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Local deployment with Datakit
  await FTMobileFlutter.sdkConfig(
    datakitUrl: datakitUrl,
  );

  // Use the public DataWay
  await FTMobileFlutter.sdkConfig(
    datawayUrl: datawayUrl,
    cliToken: cliToken,
  );
}

Blacklist Filtering¶

Flutter SDK 0.5.7 and above supports filtering RUM and Log data before it is written to the local cache. This capability is enabled by default. You can disable SDK-side filtering by setting enableDataFilter: false.

Blacklist rules can be configured centrally in the Blacklist page of a Guance workspace, and the SDK pulls them automatically from DataKit or DataWay. They can also be configured in-app via FTMobileFlutter.sdkConfig(dataFilters: ...). Both methods correspond to the same blacklist filtering capability and can be used together. If any rule matches, the data entry is discarded.

Blacklist filtering runs after lineDataModifier and before writing to the local cache. If both lineDataModifier and blacklist filtering are configured, the filtering rules are evaluated against the modified data.

enableDataFilter only controls rule pulling and filtering on the SDK side. Once set to false, the SDK no longer applies dataFilters or pulls workspace rules. When reporting via DataKit, workspace blacklists may still be enforced on the DataKit side.

Data Filter operates on the SDK data write pipeline. Too many rules or overly complex regular expressions may affect data write performance. It is recommended to configure only necessary rules.

await FTMobileFlutter.sdkConfig(
  datawayUrl: datawayUrl,
  cliToken: cliToken,
  enableDataFilter: true,
  dataFilters: {
    'logging': [
      "{ source in [ 'df_rum_ios_log', 'df_rum_android_log' ] and message match [ 'timeout' ] }",
    ],
    'rum': [
      "{ resource_status match [ '5..' ] }",
    ],
  },
);

The SDK pulls workspace blacklist rules immediately upon initialization. Subsequent pull intervals follow the pull_interval returned by the server. If the server does not return a valid value, the SDK uses 10 seconds as a fallback interval. pull_interval supports plain seconds or unit-qualified strings, such as 10, 30s, 2m, and 1h.

Rule Syntax¶

The Data Filter rule syntax is basically the same as the blacklist filtering rule syntax. For the complete syntax, see Blacklist Filtering Rules.

The key of dataFilters indicates the data category. The SDK currently supports:

Each rule is expressed as { condition }. Data under a category is filtered when it matches any rule. Rules can use the tag and field fields of the data, as well as the source and measurement fields that identify the data type.

For field value formats and operator semantics, refer to Field Value Format Description and Operator Description in the blacklist filtering rules.

Field values in SDK rule strings should use the array format. The negative operators support not in and not match, and are compatible with notin, notmatch, and not_in used in server-delivered rules.

{ status in [ 'debug' ] and env not in [ 'prod' ] and message not match [ '.*error.*' ] }

Binding and Unbinding User Information¶

Usage¶

/// Binds a user
///
/// [userid] User ID
/// [userName] User name
/// [userEmail] User email
/// [userExt] Extended data
static Future<void> bindRUMUserData(String userId,
    {String? userName, String? userEmail, Map<String, String>? ext})

/// Unbinds a user
static Future<void> unbindRUMUserData()

Code Example¶

FTMobileFlutter.bindRUMUserData("flutterUser");

FTMobileFlutter.unbindRUMUserData();

For rules on adding to ext, see Field Conflict Description.

Runtime Capabilities¶

Manual Data Sync¶

FTMobileFlutter.flushSyncData();

Manual data sync is only required when autoSync: false.