Flutter Monitoring Setup (Android) - Real User Monitoring

Atatus Real User Monitoring (RUM) for Flutter lets you monitor the real user experience of your Flutter applications. The SDK automatically tracks views, user actions, network requests, errors, and crashes, and sends them to your Atatus dashboard.

Prerequisites

• Flutter 3.27.0 or higher.
• Dart SDK 3.6.0 or higher.
• Android minSdkVersion of 23 or higher.
• Android compileSdkVersion of 34 or higher.
• A RUM application created in Atatus, which gives you a License Key (licenseKey).

Setup

1. Add the Plugins

Add the atatus_flutter_plugin dependency to your pubspec.yaml. To also monitor HTTP network requests, add the atatus_tracking_http_client and atatus_dio dependencies alongside dio:

dependencies:
  atatus_flutter_plugin: ^1.0.0
  # For tracking HTTP network requests
  atatus_tracking_http_client: ^1.0.0
  # For tracking Dio HTTP requests
  atatus_dio: ^1.0.0

Then fetch the packages:

flutter pub get

2. Initialize the Library

In your lib/main.dart, configure the SDK with your License Key (licenseKey), environment (env) and variant (e.g. release). To enable automatic tracking of crash and error events on Android, set nativeCrashReportEnabled to true. Then start your app inside AtatusSdk.runApp. To also enable HTTP network request tracking, call enableHttpTracking() on the configuration. Running your app this way ensures errors raised during startup are also captured.

To connect mobile network requests to your back-end APM traces (distributed tracing), set firstPartyHosts to your API domains. Use traceSampleRate on AtatusRumConfiguration to control the percentage of requests that generate a full distributed trace (defaults to 20.0; set to 100.0 to trace every request).

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: 'release',
    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: 20.0)
      traceSampleRate: 20.0,
    ),
  )..enableHttpTracking();

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

3. Automatically Track Views

To track screen transitions as RUM views, add the AtatusNavigationObserver to your app's routing configuration. Without this step, user views will not appear in the dashboard.

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

// lib/core/router/app_router.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 defining your root MaterialApp widget):

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

4. Automatically Track User Actions

To capture taps on buttons and other interactive widgets as RUM actions, wrap your root MaterialApp widget inside a RumUserActionDetector. Without this step, user actions will not be captured.

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

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

5. Track Network Requests with Dio

If your application uses the dio package for network requests, register the Atatus interceptor to automatically trace HTTP calls, measure response times, and log request failures.

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

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

final dio = Dio();

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

Verify Your Integration

Build and run your application on a supported Android device or emulator:

flutter run

Once the application starts, views, user actions, network requests, and errors will be monitored and displayed in the Atatus RUM dashboard. To quickly verify that the SDK is reporting data, trigger a test error from any part of your code:

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

Related Documentation

• Flutter Agent Configuration Options — Configure user session tracking, custom attributes, manual action and resource tracking, performance timings, event filtering, sampling control, and GDPR consent.
• Flutter Log Collection — Send structured log messages from your Flutter application and configure log correlation to connect application logs with RUM sessions.
• Android (Kotlin) Monitoring — Instrument native Android applications with Atatus Real User Monitoring.
• Application Monitoring — Connect mobile network requests to back-end traces for end-to-end visibility.
• Alerting — Configure alert policies to receive notifications on errors, performance regressions, and availability changes.