Help Docs

Mobile APM for Flutter applications

The Site24x7 Flutter plugin monitors your Flutter mobile app’s HTTP calls, crashes, screen load times, user taps, and custom data on Android and iOS. You can group this data by transactions, components, users, and sessions to find and fix performance problems.

Prerequisites

Before you start, make sure your project meets these minimum versions.

Component Minimum version
Flutter 3.32.8
Dart SDK 3.8.1
Android minSdkVersion 21 (Android 5.0), compileSdkVersion 35
iOS 14.0
Xcode 16.1
CocoaPods 1.16.2
Dio package (if used) 5.3.0
http package (if used) 1.1.0

Get the app key:

Go to APM > Mobile APM in the Site24x7 web client, click the hamburger icon next to your application’s name, and select Copy App Key.

Getting started

Follow the steps below to add apm_mobileapm_flutter_plugin to your Flutter app.

  1. To install the plugin, run the following command.
    flutter pub add apm_mobileapm_flutter_plugin
  2. Open the pubspec.yaml file in your application folder and verify that apm_mobileapm_flutter_plugin has been added to the dependencies section, as shown below.
    dependencies:
    apm_mobileapm_flutter_plugin: ^2.0.0

Installation steps for iOS

  1. Add the Site24x7APM pod to the Podfile located in project_directory/ios/.
    platform :ios, '14.0'

    target 'Runner' do
    # ...existing lines...
    pod 'Site24x7APM'
    end
  2. Run the following commands from your project’s root folder.
    cd ios
    pod install
Note

If pod install can’t find Site24x7APM, run pod repo update and then run pod install again.

Installation steps for Android

  1. Add the Zoho Maven URL to the project-level build file in the android folder of your application.
    • If your project uses android/build.gradle (Groovy):
      allprojects {
      repositories {
      google()
      mavenCentral()
      maven { url 'https://maven.zohodl.com' }
      }
      }

    • If your project uses android/build.gradle.kts (Kotlin):
      allprojects {
      repositories {
      google()
      mavenCentral()
      maven { url = uri("https://maven.zohodl.com") }
      }
      }
  2. Make sure minSdk is 21 or higher in android/app/build.gradle or android/app/build.gradle.kts.
    android {
    defaultConfig {
    minSdk = 21
    }
    }
Note

You don’t need to add the INTERNET permission. The plugin adds it to your application automatically.

Usage in Flutter applications

Import ApmMobileapmFlutterPlugin from the apm_mobileapm_flutter_plugin.dart file as follows:

import 'package:apm_mobileapm_flutter_plugin/apm_mobileapm_flutter_plugin.dart';

APIs to capture other parameters

Use these APIs to start the agent, track screens, network calls, and errors, and add your own data. Each section below shows the syntax.

Initialize the agent

Start the Site24x7 agent in your main() method, before runApp(). The code below also captures uncaught Flutter errors and async errors.

import 'dart:ui';

import 'package:flutter/material.dart';
import 'package:apm_mobileapm_flutter_plugin/apm_mobileapm_flutter_plugin.dart';

Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();

// Capture errors from the Flutter framework (non-async errors)
FlutterError.onError =
ApmMobileapmFlutterPlugin.instance.captureFlutterError;

// Capture uncaught async errors
PlatformDispatcher.instance.onError = (error, stack) {
ApmMobileapmFlutterPlugin.instance.platformDispatcherErrorCallback(error, stack);
return true;
};

// Start the agent
await ApmMobileapmFlutterPlugin.instance.startMonitoring("appKey", 15);

runApp(const MyApp());
}

Where,

appKey: The unique application key used to identify your app in Site24x7.

Note

To get the app key, see Prerequisites.

uploadInterval: The time interval (in seconds) at which data is sent to Site24x7 servers.

Note

We recommend an upload interval of 15 seconds. The value must be greater than 0.

Note
  • Make sure to call WidgetsFlutterBinding.ensureInitialized(); before assigning error callbacks in the main method.
  • Use await with startMonitoring(). The other APIs on this page do nothing until the agent has started.
  • The onError callback must return true to tell Flutter that the error has been handled. captureFlutterError still prints Flutter errors to your debug console.
Configure screen tracking

Add Site24x7NavigatorObserver() to your app once, and every screen your users open is tracked automatically. For each screen, the agent records the load time (from navigation to the first drawn frame) and adds a navigation breadcrumb that you'll see in crash reports. Dialogs, bottom sheets, and pop-up menus are not counted as screens.

Navigator example:

MaterialApp(
navigatorObservers: [Site24x7NavigatorObserver()],
routes: {
'/': (context) => const HomeScreen(),
'/cart': (context) => const CartScreen(),
},
);

go_router example:

final router = GoRouter(
observers: [Site24x7NavigatorObserver()],
routes: [
GoRoute(
path: '/',
builder: (context, state) => const HomeScreen(),
),
GoRoute(
path: '/cart',
builder: (context, state) => const CartScreen(),
),
],
);

MaterialApp.router(routerConfig: router);
Note

If you use ShellRoute in go_router, add Site24x7NavigatorObserver() to the observers of the shell route too. Otherwise, screens inside the shell aren’t tracked.

The observer also works with other routing packages built on Flutter’s Navigator, such as auto_route, beamer, fluro, routemaster, flutter_modular, and qlevar_router.

Name your routes:

The screen name shown in Site24x7 comes from the route name. Routes without a name are reported as Screen or not tracked at all. To name a route that you push directly, use RouteSettings:

Navigator.push(
context,
MaterialPageRoute(
settings: const RouteSettings(name: 'ProductDetails'),
builder: (context) => const ProductDetailsScreen(),
),
);

Readable screen names (optional):

To turn URL-style route paths into readable names, use Site24x7NavigatorObserver(deriveScreenNames: true). IDs in the path are grouped, so every product page appears as one screen.

Route name Screen name in Site24x7
/ Home
/products Products
/user/profile User/Profile
/products/42 Products/:id

Manual screen tracking (optional):

For content that changes without a navigation, such as tabs in a BottomNavigationBar or PageView, record the screen yourself with addScreen():

final start = DateTime.now();
// ... after the tab's content is shown:
final loadTime = DateTime.now().difference(start).inMilliseconds;
ApmMobileapmFlutterPlugin.instance.addScreen(
"OrdersTab",
loadTime.toDouble(),
start.millisecondsSinceEpoch.toDouble(),
);

Where:

  • name: The screen name to show in Site24x7.
  • loadTime: The time taken to load the screen, in milliseconds.
  • startTime: When the screen started loading, in milliseconds since epoch.
Note

Don't call addScreen() for screens that the observer already tracks, or they'll be counted twice.

Network monitoring

Network monitoring capabilities include support for HTTP and Dio packages, allowing for the capture of API calls made using these packages.

HTTP package:

import 'package:http/http.dart' as http;
import 'package:apm_mobileapm_flutter_plugin/apm_mobileapm_flutter_plugin.dart';

final client = Site24x7HttpClient();

// Or wrap an existing client:
// final client = Site24x7HttpClient(client: http.Client());

final http.Response response =
await client.get(Uri.parse('https://api.example.com/orders'));

Dio package:

import 'package:dio/dio.dart';
import 'package:apm_mobileapm_flutter_plugin/apm_mobileapm_flutter_plugin.dart';

final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));

// Add your own interceptors and settings first, then:
dio.enableSite24x7();

final response = await dio.get('/orders');
Note
  • Ensure that the required http or Dio package is installed before making API calls.
  • Call enableSite24x7() after completing all other Dio configurations. If you modify the Dio object's httpClientAdapter afterward, Site24x7 stops capturing its API calls.
Error monitoring

To capture caught exceptions:

try {
await loadProfile();
} catch (error, stack) {
ApmMobileapmFlutterPlugin.instance.captureException(
error,
stack,
reason: 'Failed to load profile',
);
}

Native crashes:

To also capture crashes in native Android (Java or Kotlin) and iOS (Swift or Objective-C) code, call this after startMonitoring():

await ApmMobileapmFlutterPlugin.instance.enableErrorReporting();
Managing transactions and components

A transaction groups the operations of one user flow. Inside a transaction, you can start and stop one or more components.

ApmMobileapmFlutterPlugin.instance.startTransaction("listing_blogs");

//Grouping various operations using components.
ApmMobileapmFlutterPlugin.instance.startComponent("listing_blogs", "http_request");
//your code/logic
ApmMobileapmFlutterPlugin.instance.stopComponent("listing_blogs", "http_request");

ApmMobileapmFlutterPlugin.instance.startComponent("listing_blogs", "view_data_onto_screen");
//your code/logic
ApmMobileapmFlutterPlugin.instance.stopComponent("listing_blogs", "view_data_onto_screen");

ApmMobileapmFlutterPlugin.instance.stopTransaction("listing_blogs");
Note

Stop all components before you stop their transaction.

User tracking

To track a specific user, set a unique user ID, for example right after the user logs in. If you don’t set one, Site24x7 generates a random GUID and uses it as the user ID.

ApmMobileapmFlutterPlugin.instance.setUserId("user@example.com");
Adding breadcrumbs

Breadcrumbs show the steps a user took before a crash. Navigation breadcrumbs are added automatically by Site24x7NavigatorObserver. To add your own breadcrumb, use:

ApmMobileapmFlutterPlugin.instance.addBreadcrumb(event, message);

// Example:
ApmMobileapmFlutterPlugin.instance.addBreadcrumb("Info", "download completed");
Custom events

Record actions that matter to you, with optional details.

// Any custom event
await ApmMobileapmFlutterPlugin.instance.recordCustomEvent(
'video_played',
attributes: {'category': 'tutorial'},
kpis: {'duration_sec': 42},
);

// Business events, such as purchases or sign-ups
await ApmMobileapmFlutterPlugin.instance.recordBusinessEvent(
'purchase_completed',
attributes: {'plan': 'Premium', 'currency': 'USD'},
kpis: {'amount': 29.99},
);

// Error events, counted by error type
await ApmMobileapmFlutterPlugin.instance.recordErrorEvent('payment_failed');

Where:

  • attributes (optional): Text details about the event, as key-value pairs.
  • kpis (optional): Numeric values for the event, such as an amount or a duration.
Custom tags

Tags are key-value pairs added to the current session. Use them to filter your performance reports, for example by plan or region. You can add up to 100 tags per session.

// Add or update tags
await ApmMobileapmFlutterPlugin.instance.setTags({'plan': 'premium', 'region': 'US'});

// Read tags
final plan = await ApmMobileapmFlutterPlugin.instance.getTag('plan');
final allTags = await ApmMobileapmFlutterPlugin.instance.getAllTags();

// Remove tags
await ApmMobileapmFlutterPlugin.instance.removeTag('plan');
await ApmMobileapmFlutterPlugin.instance.clearTags();
Click tracking

Automatic click tracking. Wrap your app once, and taps on buttons and other interactive widgets are recorded automatically.

runApp(
ApmMobileapmFlutterPlugin.instance.enableAutomaticClickTracking(
child: const MyApp(),
),
);
Note

When enabling automatic click tracking, replace the existing runApp(const MyApp()); call with the runApp() implementation shown above. Do not call runApp() twice.

Each tap is named after the widget type and its text, for example FilledButton_Add_To_Cart. To give a widget a name of your choice, add a key that starts with s247_:

ElevatedButton(
key: const ValueKey('s247_checkout_pay'),
onPressed: pay,
child: const Text('Pay'),
);

Manual click tracking. To record a click yourself, use:

ApmMobileapmFlutterPlugin.instance.recordClickEvent('checkout_pay_button');
Note

Actions done with the keyboard, such as pressing Enter to submit, aren't captured automatically. Use recordClickEvent() for them.

Note

If you build your app with --obfuscate, widget type names are hidden. Use s247_ keys so that taps keep readable names.

Screen rendering metrics (TTID and TTFD)

The agent can measure two rendering times for each screen tracked by Site24x7NavigatorObserver:

  • Time to Initial Display (TTID): The time from navigation until the screen's first frame is drawn. It's recorded automatically.
  • Time to Full Display (TTFD): The time until the screen's content, such as data and images, has fully loaded.

On iOS, turn on these metrics once, after startMonitoring(). On Android, they're on by default, and the call is safe to keep for both platforms.

await ApmMobileapmFlutterPlugin.instance.enableScreenRenderingMetrics();

To record TTFD, call reportFullyDisplayed() when the screen's content has loaded:

@override
void initState() {
super.initState();
_loadProducts().then((_) {
if (mounted) ApmMobileapmFlutterPlugin.instance.reportFullyDisplayed();
});
}
Note

If you don't call reportFullyDisplayed() within 30 seconds, the agent records TTFD at 30 seconds so the metric isn't empty. To change this limit, use Site24x7NavigatorObserver(ttfdDeadline: const Duration(seconds: 10)). Set it to Duration.zero to turn it off.

Setting the environment

To keep data from your development, staging, and production builds apart, set the environment after startMonitoring():

await ApmMobileapmFlutterPlugin.instance.setEnvironment('production');
Manual flush

You can use the API provided below to promptly send data to the Site24x7 servers instead of waiting for the next upload interval.

ApmMobileapmFlutterPlugin.instance.flush();
Forced application crash

You can force your application to crash and display an error message: This is a site24x7 crash.

ApmMobileapmFlutterPlugin.instance.crashApplication();
Other APIs

These APIs cover less common needs.

API What it does Platform
startMonitoringWithEndPoint(appKey, uploadInterval, endPoint) Starts the agent and sends data to the endpoint you specify. Android, iOS
addHttpCall(url, requestMethod, startTime, loadTime, statusCode) Records an HTTP call made with a library other than http or Dio. Android, iOS
startScreenTracking(screenName),
captureTTID(screenName, startTime),
captureTTFD(screenName, startTime)
Records TTID and TTFD yourself, for screens the observer doesn't track. startTime is the value returned by startScreenTracking(). Android, iOS
appendWebViewSessionParams(url) Adds Site24x7 session details to a URL before you open it in a WebView, so the web session links to the app session. Android, iOS
getUserSessionId(),
getUserGuid()
Returns the current session ID and user GUID. Android, iOS
enableTouchEventTracking() Tracks taps on native Android and iOS views. For Flutter widgets, use Click tracking. Android, iOS
setSessionFromWebUri(uri) Links the app session to a web session from a deep link. Android only

Upgrading from site24x7_flutter_plugin

Version 2.0.0 is backward compatible with site24x7_flutter_plugin 1.0.0 and apm_mobileapm_flutter_plugin 1.1.0. The class name and all existing APIs stay the same, so your monitoring code keeps working after a few setup changes. Upgrading also moves your app to the data format that current Site24x7 servers expect.

  1. In pubspec.yaml, remove site24x7_flutter_plugin and add the new package. If you already use apm_mobileapm_flutter_plugin, change the version to ^2.0.0.
    dependencies:
    apm_mobileapm_flutter_plugin: ^2.0.0
  2. Update every import line.
    // Old (1.0.0)
    import 'package:site24x7_flutter_plugin/site24x7_flutter_plugin.dart';

    // Old (1.1.0)
    import 'package:apm_mobileapm_flutter_plugin/site24x7_flutter_plugin.dart';

    // New (2.0.0)
    import 'package:apm_mobileapm_flutter_plugin/apm_mobileapm_flutter_plugin.dart';
  3. Set the iOS platform to 14.0 and Android minSdk to 21, as described in the installation steps.
  4. If you're upgrading from 1.0.0 and call addScreen(), pass loadTime and startTime as double values, for example loadTime.toDouble().
  5. Add await before startMonitoring(), so that API calls made right after it aren't missed.
  6. Run flutter pub get, then run pod install in the ios folder. If pod install reports a version conflict for Site24x7APM, run pod update Site24x7APM.

All other APIs work as before.

Release notes

Version 2.0.0

06 October 2026

Enhancements:

  • Support for automatic screen tracking, including load time, with Site24x7NavigatorObserver. Works with Navigator, go_router, and other routing packages.
  • Support for readable screen names using deriveScreenNames.
  • Support for screen rendering metrics: Time to Initial Display (TTID) and Time to Full Display (TTFD).
  • Support for custom events, business events, and error events.
  • Support for custom tags.
  • Support for automatic and manual click tracking.
  • Support for capturing crashes in native Android and iOS code.
  • Support for setting the environment.
  • Support for linking WebView and deep-link web sessions to app sessions.
  • Support for server time (time to first byte) and download time for HTTP calls made with Dio.

Bug fixes:

  • Fixed an Android crash that occurred when the app resumed right after a permission dialog was closed.
  • On iOS, clicks, HTTP calls, and errors are now reported under the correct Flutter screen.
  • Updated the data format to match current Site24x7 servers.

Requirements: Flutter 3.32.8, Dart 3.8.1, Android minSdkVersion 21, and iOS 14.0 or later.


Version 1.1.0

06 May 2026

  • Renamed the package from site24x7_flutter_plugin to apm_mobileapm_flutter_plugin.
  • HTTP call URLs are now recorded without query parameters and are shortened to 200 characters.
  • Android minSdkVersion raised to 21.

Version 1.0.0

05 February 2024

Enhancements:

  • Support for tracking HTTP calls with the request method, response time, throughput, status codes, platform, and screens.
  • Support for tracking screens based on the response time, throughput, and count.
  • Support for automatic tracking of navigations.
  • Support for manually tracking views.
  • Enabled user sessions tracking with a session timeout of 15 minutes.
  • Support for manually adding user IDs.
  • Support for tracking async and non-async crashes using agent-provided callbacks.
  • Support for manually adding breadcrumbs.
  • Support for packages such as HTTP and Dio.

Was this document helpful?

Would you like to help us improve our documents? Tell us what you think we could do better.


We're sorry to hear that you're not satisfied with the document. We'd love to learn what we could do to improve the experience.


Thanks for taking the time to share your feedback. We'll use your feedback to improve our online help resources.

Shortlink has been copied!