Flutter App Integration¶

Collect metrics data from various Flutter apps and analyze app-side performance through visualization.

Reading Path¶

First-time integration: Start with Quick Start
Complete integration: Continue reading this article
Initialization parameters: Refer to SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
Custom capabilities: Refer to Custom Tag Usage, Data Collection Custom Rules, Data Collection Desensitization
Advanced scenarios: Refer to WebView Data Monitoring, Native and Flutter Hybrid Development, Flutter Session Replay, Publish Package Related Configuration
Flutter Web projects: The current Flutter SDK does not provide a Web bridge. Please follow Web App Integration to use the Browser RUM SDK.
Troubleshooting: Refer to Troubleshooting
Data model: Refer to App Data Collection

Prerequisites¶

Note: If you have enabled the RUM Headless service, the prerequisites are automatically configured for you. You can directly integrate the app.

Install DataKit
Configure the RUM Collector
Configure DataKit to be accessible via the public network and install the IP Geolocation database

App Integration¶

Note

The current Flutter version only supports Android and iOS platforms.

Navigate to RUM > Create > Android/iOS
Create two separate apps for Flutter Android and Flutter iOS to receive RUM data from the Android and iOS platforms respectively.
Enter the corresponding app name and app ID for each platform's app.
Choose the app integration method:
- Public Network DataWay: Directly receives RUM data without installing the DataKit collector.
- Local environment deployment: Receives RUM data after meeting the prerequisites.

Flutter Web Projects¶

ft_mobile_agent_flutter currently only provides Android / iOS native bridging capabilities and does not provide a Flutter Web bridge.

If the app runs on Flutter Web, please create a Web type RUM app and follow Web App Integration to use the Browser RUM SDK. This method belongs to Browser RUM SDK integration, does not use the Android / iOS native bridging APIs mentioned later in this article, and does not require calling ft_mobile_agent_flutter initialization for Web RUM in Dart code.

The integration location for Flutter Web projects is typically web/index.html in the project root directory. You can load the Browser RUM SDK or business-side initialization scripts before the Flutter startup script. Do not modify the build/web directory, as it is a Flutter build artifact and will be regenerated after executing flutter build web.

Installation¶

Pub.Dev: ft_mobile_agent_flutter

Source Code: https://github.com/GuanceCloud/datakit-flutter

Demo: https://github.com/GuanceCloud/datakit-flutter/example

Execute in the project path:

flutter pub add ft_mobile_agent_flutter

This will add the dependency in the package's pubspec.yaml:

dependencies:
  ft_mobile_agent_flutter: [latest_version]

  # For Flutter 2.0 compatibility, use the following reference method
  ft_mobile_agent_flutter:
    git:
url: https://github.com/GuanceCloud/datakit-flutter.git
ref: [github_legacy_lastest_tag]

Import in Dart code:

import 'package:ft_mobile_agent_flutter/ft_mobile_agent_flutter.dart';

Starting from ft_mobile_agent_flutter 0.5.7, Session Replay is provided by the independent package ft_session_replay_flutter. To enable session replay, please continue reading Flutter Session Replay.

Additional Android Integration Configuration¶

Configure the Gradle Plugin ft-plugin for collecting App launch events, as well as Android Native-related events (page navigation, click events, Native network requests, WebView data).
To count launch times and measure launch duration, you need to customize the Application and declare it in AndroidManifest.xml.

import io.flutter.app.FlutterApplication

/**
 * If you need to count [Launch Times] and [Launch Duration], add a custom Application here.
 */
class CustomApplication : FlutterApplication() {
}

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.ft.sdk.flutter.agent_example">
  <application android:name=".CustomApplication">
    //...
  </application>
</manifest>

Detailed Configuration Entries¶

Advanced Scenarios¶

Conflict Field Explanation¶

Special key: track_id, used for tracking functionality.
When a user adds a custom tag via globalContext that conflicts with an SDK's own tag, the SDK's tag will override the user-set value.
It is recommended to add a project abbreviation prefix to tag names, e.g., custom_tag_name.
The key values used in the project can be referenced from Android constant definitions: Constants.java