> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK integration

> Integrate Flashduty RUM SDK into Flutter applications to collect views, actions, network requests, errors, and crashes

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.

<Info>
  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.
</Info>

## 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`.

<Note>
  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`.
</Note>

```yaml pubspec.yaml theme={null}
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.

```dart main.dart theme={null}
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());
  });
}
```

<Warning>
  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.
</Warning>

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:

```dart theme={null}
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.

```dart theme={null}
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';

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

<Note>
  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.
</Note>

For scenarios that do not use named routes, you can use `DatadogNavigationObserverProvider` together with `DatadogRouteAwareMixin` to manage views manually.

## Track user actions

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.

```dart theme={null}
// 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`.

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

<Warning>
  `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.
</Warning>

## 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.

```dart theme={null}
DatadogSdk.instance.setUserInfo(
  id: 'user-1001',
  name: 'Alice',
  email: 'alice@example.com',
);
```

Clear user information when the user signs out:

```dart theme={null}
DatadogSdk.instance.setUserInfo();
```

## Report errors

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

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

<Note>
  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 <a href="/en/rum/sdk/flutter/advanced-config">Advanced configuration</a>.
</Note>

## Verify the integration

After integration, verify it with these steps:

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

## Next steps

<CardGroup cols={3}>
  <Card title="Advanced configuration" icon="sliders" href="/en/rum/sdk/flutter/advanced-config">
    Configure sampling, tracking consent, event filtering, tracing, and symbol file upload.
  </Card>

  <Card title="Compatibility" icon="shield-check" href="/en/rum/sdk/flutter/compatible">
    Review supported platforms, Flutter versions, companion packages, and current limits.
  </Card>

  <Card title="Data collection" icon="database" href="/en/rum/sdk/flutter/data-collection">
    Review event types, fields, and upload behavior collected automatically and manually by the SDK.
  </Card>
</CardGroup>