Flutter Monitoring Setup

Atatus Real User Monitoring (RUM) for Flutter helps you monitor the real user experience of your Flutter applications. The SDK collects views, user interactions, network requests, errors, and crashes, and sends the data to your Atatus dashboard.

Prerequisites

• Flutter 3.27.0 or higher.
• Dart SDK 3.6.0 or higher.
• Android 6.0 (API level 23) or higher.
• iOS 15.0 or higher.

Platform support

Android and iOS support the same feature set:

Setup

1. Add the SDK dependency

Add the Atatus Flutter RUM SDK to your pubspec.yaml file:

dependencies:
  atatus_flutter_plugin: ^1.0.5
  atatus_tracking_http_client: ^1.0.5
  atatus_dio: ^1.0.5

Then fetch the packages:

flutter pub get

The atatus_tracking_http_client and atatus_dio packages enable automatic network request tracking.

2. Configure your platforms

Android

Ensure your android/app/build.gradle sets minSdkVersion to at least 23 and compileSdkVersion to at least 36. The SDK needs the INTERNET permission in android/app/src/main/AndroidManifest.xml, which Flutter templates enable by default.

iOS

Set the minimum iOS version in ios/Podfile. A new Flutter project leaves this line commented out, so uncomment it and set 15.0 or higher:

platform :ios, '15.0'

Leave use_frameworks! in place, which Flutter adds by default, then install the pods:

$ cd ios && pod install

You cannot lower the 15.0 floor. The plugin links the prebuilt Atatus iOS SDK, and its XCFrameworks are built for iOS 15.0.

3. Specify application details in Atatus

In your Atatus dashboard, open the RUM application you created and note the following values:

• License Key, which authenticates the SDK with Atatus.
• Environment, which is the name you choose for the deployment, such as production or staging.

4. Initialize the SDK

Initialize the Atatus SDK in your lib/main.dart file so it starts as early as possible in the application lifecycle.

import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:atatus_tracking_http_client/atatus_tracking_http_client.dart';
import 'package:flutter/widgets.dart';

void main() {
  final configuration = AtatusConfiguration(
    licenseKey: '<LICENSE_KEY>',
    env: '<ENV_NAME>',
    appName: '<APP_NAME>',
    nativeCrashReportEnabled: true,
    // List your API domains to enable distributed tracing
    firstPartyHosts: ['api.example.com'],
    rumConfiguration: AtatusRumConfiguration(
      // Percentage of requests that generate a full trace (default: 100.0)
      traceSampleRate: 20.0,
    ),
  )..enableHttpTracking();

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

Replace the placeholders with your license key, environment, and application name.

5. Enable Real User Monitoring

Enable automatic view tracking by adding the AtatusNavigationObserver to your app's routing configuration.

If your application uses the go_router library, register the observer in your lib/core/router/app_router.dart file:

// lib/core/router/app_router.dart
import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';

final goRouterProvider = Provider<GoRouter>((ref) {
  return GoRouter(
    initialLocation: '/',
    routes: [
      // Your application routes
    ],
    observers: [
      AtatusNavigationObserver(atatusSdk: AtatusSdk.instance),
    ],
  );
});

If your application uses the standard Flutter Navigator, register the observer in your lib/app.dart (or the file that contains your root MaterialApp widget):

// lib/app.dart
MaterialApp(
  home: const HomeScreen(),
  navigatorObservers: [
    AtatusNavigationObserver(atatusSdk: AtatusSdk.instance),
  ],
);

This configuration enables automatic view tracking and long-running task tracking.

6. Track user interactions

Enable automatic user interaction tracking by wrapping your root MaterialApp widget in a RumUserActionDetector.

Update your lib/app.dart file (or the file that contains your root MaterialApp widget):

// lib/app.dart
import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';

RumUserActionDetector(
  rum: AtatusSdk.instance.rum,
  child: MaterialApp(
    home: const HomeScreen(),
    // ...
  ),
);

7. Track network requests

To automatically track network requests made with dio, add the Atatus interceptor to your Dio client.

Update your lib/core/network/dio_client.dart file:

// lib/core/network/dio_client.dart
import 'package:atatus_dio/atatus_dio.dart';
import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:dio/dio.dart';

final dio = Dio();

// Register the Atatus interceptor to enable automatic network monitoring
dio.addAtatusInterceptor(AtatusSdk.instance);

The interceptor automatically reports Dio requests as RUM resources, including details such as the URL, HTTP method, response status, and request duration.

Start monitoring

Build and run your application:

flutter run

Within a few minutes, views, user interactions, network requests, and errors appear in your Atatus dashboard. To verify the setup quickly, you can report a test error from anywhere in your code:

import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';

AtatusSdk.instance.rum?.addErrorInfo(
  'Test Atatus setup',
  RumErrorSource.source,
);

Next steps

• Connect your mobile requests to your backend with Application Monitoring.
• Set up alerts to get notified about errors and performance regressions.
• Explore Flutter Agent Configuration Options to configure user session tracking, custom attributes, and GDPR consent.
• Track Dio, gRPC, and GraphQL calls with Flutter Network Tracking.
• Connect requests to your backend with Flutter Distributed Tracing.
• Correlate web content with Flutter WebView Tracking.
• Record what your users saw with Flutter Session Replay.
• Learn about Flutter Log Collection to send structured log messages and correlate logs with RUM sessions.
• Review the native iOS options the plugin sits on with iOS Monitoring Setup.