Skip to content

Flutter App Integration

Collect telemetry data from Flutter apps and analyze their performance through visualizations.

Read More

Prerequisites

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

App Integration

Note

The current Flutter version only supports Android and iOS platforms.

  1. Navigate to RUM > Create App > Android/iOS
  2. Create two apps for Flutter Android and Flutter iOS respectively to receive RUM data from Android and iOS platforms.
  3. Enter the corresponding app name and app ID for each platform.

  4. Select the app integration method:

    • Public DataWay: Directly receive RUM data without installing the DataKit collector.
    • Local environment deployment: Receive RUM data after meeting the prerequisites.

Flutter Web Projects

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

If your app runs on Flutter Web, create a Web type RUM app and use the Browser RUM SDK as described in Web App Integration. This method is a Browser RUM SDK integration and does not use the Android/iOS native bridge APIs described later in this document, nor does it require calling ft_mobile_agent_flutter in Dart code to initialize Web RUM.

The integration point for Flutter Web projects is typically web/index.html in the project root. You can load the Browser RUM SDK or a business-side initialization script before the Flutter startup script. Do not modify the build/web directory; it is a Flutter build artifact and will be regenerated when you run 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

Run the following command in your project root:

flutter pub add ft_mobile_agent_flutter

This adds the dependency to your pubspec.yaml:

dependencies:
  ft_mobile_agent_flutter: [latest_version]

  # flutter 2.0 compatibility version uses the method below
  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 a separate package ft_session_replay_flutter. To enable session replay, continue reading Flutter Session Replay.

Android Integration Additional Configuration

  • Configure the Gradle Plugin ft-plugin to collect app launch events, Android native events (page navigation, click events, native network requests, WebView data).
  • To count launch times and launch duration, you need to customize the Application class according to the Flutter version and declare it in AndroidManifest.xml.

For Flutter 3.28.x and below, use the old approach:

import io.flutter.app.FlutterApplication

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

For Flutter 3.29.0 and above, use the new approach:

import android.app.Application

/**
 * If you need to count [launch count] and [launch duration], add a custom Application here.
 */
class CustomApplication : Application() {
}
Flutter 3.29.0 and later notes

Flutter 3.29.0 removed the v1 Android embedding, including io.flutter.app.FlutterApplication. Therefore, starting from this version, use the new approach above. To collect Android app launch events, ft-plugin needs to insert launch monitoring code in the onCreate() of the custom Application. Please directly extend android.app.Application (or androidx.multidex.MultiDexApplication); otherwise, app launch events such as launch_cold may not be collected.

<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 Entry

Advanced Scenarios

Key Conflict Field Description

  • Special key: track_id, used for tracking functionality.
  • When a user adds a custom tag via globalContext that conflicts with SDK built-in tags, the SDK tag will override the user-set value.

  • It is recommended to prefix tag names with a project abbreviation, e.g., custom_tag_name.

  • The key values used in the project can be referenced from the Android constants definition: Constants.java

FAQ

Feedback

Is this page helpful?