Flutter SDK integration

The Flutter SDK wraps the native iOS / Android SDKs and provides RUM capabilities through flashcat_flutter_plugin. After initialization, the SDK reports the application’s views, user actions, network requests, errors, and crashes to Flashduty RUM, with source: "flutter" identifying the data source.

The current SDK version is 0.1.0 and supports only the iOS and Android platforms (Flutter Web is not supported). The Dart class names still follow the upstream Datadog* naming (such as DatadogSdk and DatadogConfiguration); only the package name flashcat_flutter_plugin and the site enum FlashcatSite are rebranded. v1 does not yet include Logs, Session Replay, or the dio / gql / grpc companion packages.

Prerequisites

Before integrating the SDK, complete these steps:

Create or select a RUM application in the Flashduty console, then obtain the Application ID and Client Token
Make sure your application can reach https://browser.flashcat.cloud/api/v2/rum
Flutter SDK ≥ 3.0, Dart ≥ 3.0; iOS deployment target ≥ 12.0, Android minSdkVersion ≥ 21
Initialize the SDK early in application startup (in main())

Install the SDK

Add flashcat_flutter_plugin to pubspec.yaml, then run flutter pub get.

The pub.dev publication of flashcat_flutter_plugin is still being confirmed. To keep the dependency resolvable, the example below uses a git source. Once it is officially published to pub.dev, you can switch to the hosted form flashcat_flutter_plugin: ^0.1.0.

pubspec.yaml

dependencies:
  flashcat_flutter_plugin:
    git:
      url: https://github.com/flashcatcloud/fc-sdk-flutter
      path: packages/datadog_flutter_plugin

Initialize the SDK

We recommend initializing in main(), before runApp. When you start the application with DatadogSdk.runApp, the SDK automatically takes over FlutterError.onError and PlatformDispatcher.instance.onError, so it can collect unhandled exceptions without manual wiring.

main.dart

import 'package:flutter/widgets.dart';
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';

Future<void> main() async {
  final configuration = DatadogConfiguration(
    clientToken: '<CLIENT_TOKEN>',
    env: 'production',
    service: 'com.example.shopping',
    site: FlashcatSite.cn,
    nativeCrashReportEnabled: true, // Collect native iOS / Android crashes
    firstPartyHosts: ['api.example.com'], // Inject distributed trace headers for these hosts
    rumConfiguration: DatadogRumConfiguration(
      applicationId: '<APPLICATION_ID>',
      sessionSamplingRate: 100.0,
      // customEndpoint: 'https://your-ingest.example.com', // Custom reporting endpoint for on-premises deployments
    ),
  );

  await DatadogSdk.runApp(configuration, TrackingConsent.granted, () async {
    runApp(const MyApp());
  });
}

Do not use server-side secrets in client code. clientToken is only for client-side RUM reporting, and applicationId assigns events to the RUM application.

If you need to control the startup flow yourself, outside of runApp, you can also initialize manually, but you must wire up error collection yourself:

WidgetsFlutterBinding.ensureInitialized();
await DatadogSdk.instance.initialize(configuration, TrackingConsent.granted);

final originalOnError = FlutterError.onError;
FlutterError.onError = (details) {
  DatadogSdk.instance.rum?.handleFlutterError(details);
  originalOnError?.call(details);
};

Track views

Add a DatadogNavigationObserver to your MaterialApp (or CupertinoApp), and the SDK automatically records the Navigator’s route changes as RUM views.

import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';

MaterialApp(
  navigatorObservers: [
    DatadogNavigationObserver(datadogSdk: DatadogSdk.instance),
  ],
  home: const HomeScreen(),
);

The DatadogNavigationObserver constructor uses the named parameter datadogSdk:. By default it uses the route’s settings.name as the view name; you can customize the view name or filter routes through the viewInfoExtractor callback.

For scenarios that do not use named routes, you can use DatadogNavigationObserverProvider together with DatadogRouteAwareMixin to manage views manually. In the RUM configuration, trackFrustrations is enabled by default. After you wrap your application subtree with RumUserActionDetector, the SDK automatically recognizes interactions such as taps and generates action events; you can also record actions manually.

// Automatically recognize user interactions in the subtree
RumUserActionDetector(
  rum: DatadogSdk.instance.rum,
  child: const MyApp(),
);

// Manually record one action
DatadogSdk.instance.rum?.addAction(RumActionType.tap, 'Checkout');

Track network requests

Automatic network collection is provided by the separate datadog_tracking_http_client package and enabled through the enableHttpTracking() extension method on the configuration object. It globally replaces HttpClient, records dart:io / http requests as RUM resources, and injects W3C trace headers for hosts that match firstPartyHosts.

final configuration = DatadogConfiguration(
  clientToken: '<CLIENT_TOKEN>',
  env: 'production',
  site: FlashcatSite.cn,
  firstPartyHosts: ['api.example.com'],
  rumConfiguration: DatadogRumConfiguration(applicationId: '<APPLICATION_ID>'),
)..enableHttpTracking();

datadog_tracking_http_client currently declares its dependency on datadog_flutter_plugin (^3.0.0), which cannot be resolved directly with this fork’s flashcat_flutter_plugin 0.1.0. When you enable network collection, add a dependency_overrides entry in pubspec.yaml pointing to this fork. This capability is not part of the v1 core scope and can be integrated as needed.

Identify users

After sign-in, you can set the current user. The SDK writes the user fields to the usr object on subsequent RUM events.

DatadogSdk.instance.setUserInfo(
  id: 'user-1001',
  name: 'Alice',
  email: 'alice@example.com',
);

Clear user information when the user signs out:

DatadogSdk.instance.setUserInfo();

Report errors

When you use DatadogSdk.runApp, unhandled exceptions are collected automatically. You can also manually report caught exceptions:

try {
  // ... business logic ...
} catch (e, st) {
  DatadogSdk.instance.rum?.addError(e, RumErrorSource.source, stackTrace: st);
}

Crash and error stacks require uploaded symbol files to resolve back to source locations. Flutter symbols, iOS dSYM, and Android mapping files are uploaded through the FlashCat CLI, and the version used at upload time must match the version in the SDK initialization. See Advanced configuration.

Verify the integration

After integration, verify it with these steps:

Temporarily set DatadogSdk.instance.sdkVerbosity = CoreLoggerLevel.debug during initialization, and inspect the console logs to observe the SDK’s reporting behavior
Run the application and trigger page navigation, taps, network requests, or a manual error
In the Flashduty RUM application, filter for source:flutter and confirm that view, action, resource, or error events appear
For network requests, check whether the backend receives the W3C traceparent

Next steps

Advanced configuration

Configure sampling, tracking consent, event filtering, tracing, and symbol file upload.

Compatibility

Review supported platforms, Flutter versions, companion packages, and current limits.

Data collection

Review event types, fields, and upload behavior collected automatically and manually by the SDK.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Prerequisites

Install the SDK

Initialize the SDK

Track views

Track user actions

Track network requests

Identify users

Report errors

Verify the integration

Next steps

Advanced configuration

Compatibility

Data collection

​Prerequisites

​Install the SDK

​Initialize the SDK

​Track views

​Track user actions

​Track network requests

​Identify users

​Report errors

​Verify the integration

​Next steps

Advanced configuration

Compatibility

Data collection

Prerequisites

Install the SDK

Initialize the SDK

Track views

Track user actions

Track network requests

Identify users

Report errors

Verify the integration

Next steps