The Dynatrace Flutter plugin adds the Dynatrace OneAgent for Android and iOS to your Flutter app and provides an API to use manual instrumentation for Flutter/Dart data capture.
For detailed technical documentation, see API for Flutter.
Before you begin, ensure your environment meets the following requirements:
| Requirement | Minimum Version |
|---|---|
Dynatrace version | 1.203 |
Flutter | 3.24.0 |
Dart | 3.0.0 |
Android API Level | 23 |
iOS SDK | 15 |
Gradle | 8.14.x |
Android Gradle Plugin | 8.1.1 |
Java | 17 |
In Dynatrace, go to Mobile.
Select Create mobile app.
Enter a name for your application and select Create mobile app. The application settings page opens.
From the application settings, select Instrumentation wizard > Flutter.
Follow the steps described in the wizard.
A custom action measures a part of your app that automatic instrumentation doesn't detect. Web requests and values you report while the action is open are attached to it.
Call enterAction() to open an action, and call leaveAction() to close it when the work is done.
DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');//Perform the action and whatever else is needed.myAction.leaveAction();
leaveAction() closes the action again. To report values for this action before closing, see Report values.
Action names are limited to 250 characters and will be truncated if they exceed this limit.
Call cancel() instead of leaveAction() to discard an action. The action and all of its unfinished child actions are dropped and not sent to Dynatrace.
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';final myAction = Dynatrace().enterAction('MyAction');myAction.cancel();
Call enterAction() on an open action to group related work under it. The sub-action appears under its parent action.
DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');DynatraceAction mySubAction = myAction.enterAction('MyButton Sub Action');//Perform the action and whatever else is needed.mySubAction.leaveAction();myAction.leaveAction();
enterAction() on an action that's already closed, it has no effect.You can attach events, values, and errors to an open action. They appear on that action in the user session. Once an action is closed, nothing more can be reported on it.
The following methods are available on any action returned by enterAction(), including sub-actions:
| Method | Reports |
|---|---|
| A named event |
| A string value |
| An integer value |
| A double value |
| An error with a numeric code |
Use reportStringValue() to attach a string value to the action:
DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');myAction.reportStringValue('ValueName', 'ImportantValue');myAction.leaveAction();
If you don't have a reference to the action, call the same methods on Dynatrace(). The value is attached to the most recently opened action that is still open. If no action is open, the value isn't reported.
| Method | Reports |
|---|---|
| An error with a numeric code |
| An error with name, value, reason, and stacktrace |
| A named event |
| A string value |
| An integer value |
| A double value |
Use reportStringValue() to report a string value:
Dynatrace().reportStringValue('ValueName', 'ImportantValue');
All of these methods take an optional platform parameter that limits reporting to Android or iOS. See Platform-specific reporting.
Our Flutter plugin provides a wrapper over Dart's http client. It can be used to automatically tag and time the web requests that are called.
Create a client using Dynatrace().createHttpClient():
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';var client = Dynatrace().createHttpClient();DynatraceRootAction webAction =Dynatrace().enterAction('Button Click');try {await client.get(Uri.parse('https://dynatrace.com'));} catch (error) {// insert error handling here} finally {webAction.leaveAction();client.close();}
Link web requests with a custom action. DynatraceHttpClient will automatically link a web request to the current open user action:
var client = Dynatrace().createHttpClient();DynatraceRootAction webAction =Dynatrace().enterAction('Button Click');try {await client.get(Uri.parse('https://dynatrace.com'));} catch (error) {// insert error handling here}try {await client.get(Uri.parse('https://flutter.dev'));} catch (error) {// insert error handling here}try {await client.get(Uri.parse('https://dart.dev'));} catch (error) {// insert error handling here}webAction.leaveAction();client.close();
To wrap your own client, change how request sizes are calculated or to exclude URLs from monitoring, see Web request performance on the shared HTTP page.
Use manual web request monitoring when you can't use createHttpClient(), for example with dart:io HttpClient, gRPC, or another custom networking stack. The request is timed and attached to a user action.
Don't use manual monitoring and createHttpClient() for the same request, or the request is reported twice.
Use WebRequestTiming from a DynatraceRootAction to monitor a web request:
import 'dart:io';import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';final client = HttpClient();final action = Dynatrace().enterAction('MyButton tapped - Web Action');final timing = await action.createWebRequestTiming('https://dynatrace.com');if (timing.getRequestTag().isNotEmpty) {final request = await client.getUrl(Uri.parse('https://dynatrace.com'));request.headers.set(timing.getRequestTagHeader(), timing.getRequestTag());timing.startWebRequestTiming();try {final response = await request.close();timing.stopWebRequestTiming(response.statusCode, response.reasonPhrase);} catch (error) {timing.stopWebRequestTiming(-1, error.toString());}}action.leaveAction();
Crash reporting is on by default. Once the plugin has started, it captures unhandled Dart and Flutter errors: Flutter framework errors (FlutterError.onError) and uncaught errors that reach PlatformDispatcher.instance.onError. Native crashes are captured by the native Android and iOS OneAgents.
Automatic crash reporting is enabled by default. If you prefer to handle error reporting manually, you can disable it in the configuration.
To disable automatic crash reporting, set crashReporting to false in your dynatrace.config.yaml:
Android:
android:config:"dynatrace {configurations {defaultConfig {crashReporting false}}}"
iOS:
ios:config:"<key>DTXCrashReportingEnabled</key><false/>"
Or in case of manual startup:
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';void main() {Dynatrace().start(MyApp(),configuration: Configuration(beaconUrl: 'BeaconUrl',applicationId: 'AppId',reportCrash: false),);}
To deactivate automatic crash reporting, set crashReporting to false in your dynatrace.config.yaml:
android:config:"dynatrace {configurations {defaultConfig {crashReporting false}}}"ios:config:"<key>DTXCrashReportingEnabled</key><false/>"
With manual startup, set reportCrash: false in the Configuration object:
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';void main() {Dynatrace().start(MyApp(),configuration: Configuration(beaconUrl: 'BeaconUrl',applicationId: 'AppId',reportCrash: false),);}
| Method | Reported in RUM Classic as |
|---|---|
| Error |
| Crash |
| Crash |
Use reportZoneStacktrace() for caught exceptions that you want to see in Dynatrace:
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';Future<void> syncCart() async {try {throw Exception('Cart sync failed');} catch (error, stacktrace) {await Dynatrace().reportZoneStacktrace(error, stacktrace);}}
Errors in a spawned isolate don't reach the main isolate's error handlers. To report them, pass DynatraceIsolateErrorReceivePort as the isolate's onError port:
await Isolate.spawn((message){/*Do work*/},null,onError: DynatraceIsolateErrorReceivePort().sendPort,);
If you already have an Isolate reference, you can call isolate.addDynatraceErrorListener() instead. Errors that occur before the listener is attached aren't reported:
final isolate = await Isolate.spawn((message){/*Do work*/}, null);isolate.addDynatraceErrorListener();
Call identifyUser() to tag the current session with a username or ID. You can then search for that user's sessions in Dynatrace.
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';void onLoginSucceeded(String userId) {Dynatrace().identifyUser(userId);}
Call setGPSLocation() to report the user's position. Dynatrace uses it to work out the city closest to that position.
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';void onLocationUpdated(double latitude, double longitude) {Dynatrace().setGPSLocation(latitude, longitude);}
The native OneAgents can also capture location automatically, as long as your app already requests location updates:
| Platform | Captures location from | Default |
|---|---|---|
Android |
| Off. Turn on location monitoring in the |
iOS |
| On. Location is rounded to three decimal places to protect user privacy. |
When location monitoring is turned off or no location information is available, Dynatrace uses IP addresses to determine the location of the user. For more information, see Detection of IP addresses, geolocations, and user agents in RUM Classic.
Call sendBizEvent() to report a business event, such as a completed booking or purchase. Business events are standalone: they aren't attached to a user action or user session. You can analyze them alongside your other business data in Dynatrace.
Dynatrace().sendBizEvent('com.easytravel.funnel.booking-finished', {'event.name' : 'Confirmed Booking','screen': 'booking-confirmation','product': 'Danube Anna Hotel','amount': 358.35,'currency': 'USD','reviewScore': 4.8,'arrivalDate': '2022-11-05','departureDate': '2022-11-15','journeyDuration': 10,'adultTravelers': 2,'childrenTravelers': 0});
The sendBizEvent() method supports the following parameters:
| Parameter | Description |
|---|---|
| Required. The event type, for example |
| Optional map of event attributes. Pass |
| Optional platform to report the event on. |
By default, API calls report on both Android and iOS. To report on only one platform, pass the optional platform parameter with Platform.Android or Platform.iOS. On the other platform, the call does nothing.
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';// Reported on iOS onlyfinal iosAction = Dynatrace().enterAction('MyButton tapped', platform: Platform.iOS);iosAction.leaveAction();// Reported on Android onlyfinal androidAction = Dynatrace().enterAction('MyButton tapped', platform: Platform.Android);androidAction.leaveAction();// Reported on both platformsfinal action = Dynatrace().enterAction('MyButton tapped');action.leaveAction();
For a full list of APIs, see API for Flutter.
Mobile