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:
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 ofuser-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.
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
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
Set labels
Set the labels for the Coralogix exporter.
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.
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].