Mobile Flutter

The Coralogix RUM Mobile SDK is a library (plugin) for Flutter that provides mobile telemetry instrumentation. Learn how to integrate with Coralogix's Real User Monitoring (RUM).

Overview

The Coralogix RUM Mobile SDK is a library (plugin) for Flutter that provides mobile telemetry instrumentation. The SDK captures:

HTTP requests
Unhandled/handled exceptions
Custom logs
Crashes (iOS Native using PLCrashReporter)
Views

Coralogix captures data using an SDK within your application's runtime. These platform-specific SDKs allow Coralogix to gain a deep understanding of how your application works, enabling comprehensive real-user monitoring and performance analysis.

Prerequisites

Flutter SDK version ver 3.3.0 or above.
Dart SDK version 3.4.1 - 4.0.0.

Installation

To add the Coralogix dependency, navigate to the root folder of your Flutter app and run:

flutter pub add cx_flutter_plugin

Configure

To initialize the RUM SDK, input both CXExporterOptions and CXDomain.

Future<void> initPlatformState() async {
  // Setup the cx SDK
  var userContext = UserContext(
    userId: '123',
    userName: 'John Doe',
    userEmail: '[email protected]',
    userMetadata: {'item1': '1999'},
  );
  var coralogixDomain = CXDomain.eu2;
  var options = CXExporterOptions(
    coralogixDomain: coralogixDomain,
    userContext: userContext,
    environment: 'production',
    application: 'App name',
    version: '1.0.0',
    publicKey: 'Your public key',
    ignoreUrls: [],
    ignoreErrors: [],
    customDomainUrl: 'https://you.custom.url',
    labels: {'item': 'playstation 5', 'itemPrice': 1999},
    sdkSampler: 100,
    mobileVitalsFPSSamplingRate: 150,
    instrumentations: { CXInstrumentationType.anr.value: true,
                        CXInstrumentationType.custom.value: true,
                        CXInstrumentationType.errors.value: true,
                        CXInstrumentationType.lifeCycle.value: true,
                        CXInstrumentationType.mobileVitals.value: true,
                        CXInstrumentationType.navigation.value: true,
                        CXInstrumentationType.network.value: true,
                        CXInstrumentationType.userActions.value: true},
    collectIPData: true,
    debug: true,
  );
  await CxFlutterPlugin.initSdk(options);
  // If the widget was removed from the tree while the asynchronous platform
  // message was in flight, we want to discard the reply rather than calling
  // setState to update our non-existent appearance.
  if (!mounted) return;
}

Field	Description	Example
`coralogixDomain`	The region associated with your Coralogix domain.	`US1, US2, EU1, EU2, 2PI, API`
`userContext`	User context information, such as user ID, name, email, and additional metadata.	`var userContext = UserContext( userId: '123', userName: 'John Doe', userEmail: '[email protected]', userMetadata: {'item1': '1999'}, );`
`environment`	The environment in which the application is running (e.g., production, staging).	`"production"`
`application`	The name of the application.	`"MyApp"`
`version`	The version of the application.	`"1.0.0"`
`publicKey`	Coralogix token, publicly-visible publicKey value. This is a required property.	`"my_public_key"`
`ignoreUrls`	A list of URLs to ignore for logging and monitoring purposes.	`["https://example.com/api"]`
`ignoreErrors`	A list of errors to ignore for logging and monitoring purposes.	`["NotFoundError", "TimeoutError"]`
`customDomainUrl`	A custom domain URL for sending data, if different from the default Coralogix domain.	`"https://custom-domain.example.com"`
`labels`	A set of key-value pairs for additional metadata or labels to attach to logs and monitoring data.	`{ environment: "production", region: "us-east-1"}`
`debug`	A boolean flag to enable or disable debug mode for additional logging and diagnostics.	`true` or `false`

Instrumentation

Enable or disable specific instrumentation (see the list below), with the default set to all trues. Each instrumentation controls the data the SDK will track and collect.

errors - Monitors error events.
network - Intercepts and reports network calls.
custom - Allows developers to define and track custom events, giving insights into specific actions or behaviors in the application that are critical to the business.
anr - Automatically detects Application Not Responsive (ANR) events.
mobileVitals - Automatically tracks cold/warm start times and Frame Rate (FPS).
lifeCycle - Captures the application lifecycle events as they are defined in each platform (Android/iOS).
navigation - Identifies user movement between app screens.
userActions – Catches user actions, such as button taps, tab activations, and other navigation controllers. It creates a span with a severity level of info and an event type of user-interaction, incorporating details about the element, including the text displayed on it.

Integration functions

This section lists public functions used to interact with the Coralogix RUM SDK.

Monitor network requests

Use CxHttpClient to monitor the HTTP traffic.

final client = CxHttpClient(http.Client());
await client.get(Uri.parse(url));

Report unhandled/handled exceptions

For handled exceptions, use a try/catch scheme with the reportError API.

try {
  throw StateError('state error try catch');
} catch (error, stackTrace) {
  if (error is StateError) {
    // Handle the StateError
    CxFlutterPlugin.reportError(error.message, {}, stackTrace.toString());
  }
}

or

await CxFlutterPlugin.reportError('this is an error', {'fruit': 'banana', 'price': 1.30}, "");

Report unhandled exceptions

Wrap your runApp function as follows:

void main() {
  runZonedGuarded(() {
    runApp(const MaterialApp(
      title: 'Navigation Basics',
      home: MyApp(),
    ));
  }, (error, stackTrace) {
    CxFlutterPlugin.reportError(error.toString(), {}, stackTrace.toString());
  });
}

Customize logs

await CxFlutterPlugin.log(CxLogSeverity.error, 'this is an error', {'fruit': 'banana', 'price': 1.30});

Monitor page views

await CxFlutterPlugin.setView(viewName);

Set labels

Set the labels for the Coralogix exporter.

final labels = {'stock': 'NVDA', 'price': 104};
await CxFlutterPlugin.setLabels(labels);

Set user context

var userContext = UserContext(
  userId: '456',
  userName: 'Robert Davis',
  userEmail: '[email protected]',
  userMetadata: {'car': 'tesla'},
);

await CxFlutterPlugin.setUserContext(userContext);

Shut down the exporter

Shut down the Coralogix exporter and mark it as uninitialized.

await CxFlutterPlugin.shutdown();

For more information, check Coralogix SDK Documentation.

Additional resources


External documentation	GitHub Repo

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at [email protected].

Android

Next iOS