> ## 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 advanced configuration

> Configure sampling, tracking consent, event filtering, distributed tracing, and symbol file upload for the Flutter RUM SDK

This page describes the advanced configuration options of the Flutter SDK. All configuration is passed through `DatadogConfiguration` and `DatadogRumConfiguration`.

## Sampling rate

```dart theme={null}
DatadogRumConfiguration(
  applicationId: '<APPLICATION_ID>',
  sessionSamplingRate: 100.0, // Session sampling rate
  traceSampleRate: 20.0,      // Trace sampling rate on resources
);
```

## Tracking consent

`TrackingConsent` controls whether data is collected and reported, to meet compliance requirements such as GDPR:

| Value                        | Behavior                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------- |
| `TrackingConsent.granted`    | Collect and report                                                               |
| `TrackingConsent.notGranted` | Do not collect                                                                   |
| `TrackingConsent.pending`    | Cache first, then decide whether to report or drop after the user grants consent |

```dart theme={null}
// Pass in during initialization
await DatadogSdk.runApp(configuration, TrackingConsent.pending, () async {
  runApp(const MyApp());
});

// Update after the user grants consent
DatadogSdk.instance.setTrackingConsent(TrackingConsent.granted);
```

## Event filtering and masking

Event mappers run before events are reported; return `null` to drop the event, or return it after modification. You can use them to mask sensitive fields, remove noise, or rename views.

```dart theme={null}
DatadogRumConfiguration(
  applicationId: '<APPLICATION_ID>',
  viewEventMapper: (event) => event,
  actionEventMapper: (event) => event,
  resourceEventMapper: (event) {
    // For example, remove the query token from the URL
    return event;
  },
  errorEventMapper: (event) => event,
  longTaskEventMapper: (event) => event,
);
```

## Distributed tracing

For hosts that match `firstPartyHosts`, the SDK injects the W3C `traceparent` to correlate frontend RUM with backend APM. Tracing requires network collection (`enableHttpTracking()`).

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

## Custom reporting endpoint

For on-premises deployments, override the default reporting endpoint through `customEndpoint`:

```dart theme={null}
DatadogRumConfiguration(
  applicationId: '<APPLICATION_ID>',
  customEndpoint: 'https://your-ingest.example.com',
);
```

## Symbol file upload

To resolve crash and error stacks back to source locations, you need to upload symbol files. A Flutter application may contain both Dart and native frames:

| Frame type     | Required files  | How to generate                                      |
| -------------- | --------------- | ---------------------------------------------------- |
| Dart           | Flutter symbols | `flutter build --split-debug-info=<dir> --obfuscate` |
| iOS Native     | dSYM            | Xcode build output                                   |
| Android Native | mapping files   | R8 / ProGuard output                                 |

Use the FlashCat CLI to upload symbol files:

```bash theme={null}
# Example: upload the symbol files for the corresponding version
flashcat-cli flutter-symbols upload --service <SERVICE_NAME> --version <VERSION> <symbols-dir>
```

<Warning>
  The `version` and `service` used at upload time must exactly match the values in the SDK initialization. Otherwise the console can receive crash events but cannot resolve stack frames back to source locations. Make symbol upload part of your release build process.
</Warning>

## Other configuration

| Configuration                   | Default | Description                                                                         |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `nativeCrashReportEnabled`      | false   | Whether to collect native crashes                                                   |
| `detectLongTasks`               | true    | Whether to collect long tasks                                                       |
| `longTaskThreshold`             | 0.1s    | Long task threshold                                                                 |
| `trackBackgroundEvents`         | false   | Whether to collect events while the application is in the background                |
| `batchSize` / `uploadFrequency` | —       | Upload batch size and frequency, balancing real-time delivery against battery usage |