raygun4flutter

Description:

raygun4flutter

raygun4flutter #


The world's best Flutter Crash Reporting solution.
Introduction #
Library organisation #
Raygun4Flutter is from version 1.0.0 onwards built entirely in Dart and does not rely on the native providers Raygun4Android and Raygun4Apple anymore as earlier versions of Raygun4Flutter.
The file lib/raygun4flutter.dart provides the main API entry point for Flutter users.
Requirements #

Dart SDK 3.3.0+

As of release 1.0.0 we've started to improve support for Flutter Desktop and Web. The package seems to be working fine with these targets but we'd appreciate any additional feedback on Github.
Installation #
1. Depend on it #
Run this command:
$ flutter pub add raygun4flutter
This will add a line like this to your package's pubspec.yaml (and run an implicit dart pub get):
dependencies:
raygun4flutter: ^x.y.z
copied to clipboard
Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.
2. Import it #
Now in your Dart code, you can use:
import 'package:raygun4flutter/raygun4flutter.dart';
Check the "Installing" tab on https://pub.dev/packages/raygun4flutter/install for more info.
3. Platform-specific notes #
General
If your application comprises hybrid code both using Flutter and native Android or iOS elements, please be aware that the Raygun4Flutter package will only track and report crashes from Flutter and Dart.
If you have a requirement to track crash reports across various layers and parts of your application written in different technologies you might need to implement the respective native providers for Android, iOS or other platforms of choice as well.
Android-specific
In your app's AndroidManifest.xml (usually located in your Flutter project's /android/src/main directory), make sure you have granted Internet permissions. Inside the <manifest> element add:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
copied to clipboard
if it doesn't exist yet.
Setup and usage #
Initialisation and version tracking #
Call Raygun.init() with an apiKey argument to initialise RaygunClient on application start, for example, from your initState method.
class _MyAppState extends State<MyApp> {

@override
void initState() {
super.initState();
Raygun.init(apiKey:'12345');
}

}
copied to clipboard
The .init() method can also accept an optional version argument. If this is supplied, the version of your app will be tracked across Raygun crash reports:
Raygun.init(apiKey:'12345', version:'1.4.5');
copied to clipboard
As an additional convenience way to set the version, a method .setVersion() is available. Typical use cases would most likely fall back to setting the app version in the .init() method call when you setup the library.
Capturing and sending errors #
To be able to capture errors inside Flutter, you need to add a custom FlutterError.onError handler to your main method. That redirects Flutter errors to Raygun.
Note: This only works when the app is running in "Release" mode.
FlutterError.onError = (details) {
// Default error handling
FlutterError.presentError(details);

// Raygun error handling
Raygun.sendException(
error: details.exception,
stackTrace: details.stack,
);
};
copied to clipboard
You can also catch Dart errors outside of the code controlled by the Flutter framework by calling to runApp from a runZonedGuarded and redirecting captured errors to Raygun. For example: errors that happen in asynchronous code.
Note: This works both in "Release" and "Debug" modes.
runZonedGuarded<Future<void>>(() async {
runApp(const MyApp());
}, (Object error, StackTrace stackTrace) {
Raygun.sendException(
error: error,
stackTrace: stackTrace,
);
});
copied to clipboard
Sending errors manually #
Call Raygun.sendException(error, tags, customData, stackTrace) to send errors to Raygun.
For example:
try {
// code that crashes
} catch (error) {
Raygun.sendException(error: error);
}
copied to clipboard
All arguments but error are optional. This method is mainly a convenience wrapper around the more customisable .sendCustom() method that obtains the class name and the message from the error object.
Sending custom errors manually #
Call Raygun.sendCustom(className, reason, tags, customData, stackTrace) to send custom errors to Raygun with your own customised className and reason. As with .sendException(), tags, customData and stackTrace are optional.
You can also provide an optional innerError Exception object that will be attached to the error report.
For example:
Raygun.sendCustom(
className: 'MyApp',
reason: 'test error message',
tags: ['API','Tag2'],
customData: {
'custom1': 'value',
'custom2': 42,
},
stackTrace: StackTrace.current,
innerError: Exception('Error!'),
);
copied to clipboard
Crash reports will be sent to the Raygun backend after the crash occurred. Should a user's device be offline, Raygun4Flutter will store up to 64 crash reports locally and try to send them when the device comes back online.
Other functionality #
Setting tags #
Raygun.setTags() sets a list of global tags that will be logged with every exception. This will be merged with other tags passed into manually created crash reports via sendException() and sendCustom().
Raygun.setTags(['Tag1','Tag2']);
copied to clipboard
Setting custom data #
Raygun.setCustomData() sets a global map of key-value pairs that, similar to tags, that will be logged with every exception. This will be merged with other custom data passed into manually created crash reports via sendException() and sendCustom().
Raygun.setCustomData({
'custom1': 'value',
'custom2': 42,
});
copied to clipboard
Sending breadcrumbs #
Breadcrumbs can be sent to Raygun to provide additional information to look into and debug issues stemming from crash reports. Breadcrumbs can be created in two ways.
Simple string:
Call Raygun.recordBreadcrumb(message), where message is just a string:
Raygun.recordBreadcrumb('test breadcrumb');
copied to clipboard
Using RaygunBreadcrumbMessage:
Create your own RaygunBreadcrumbMessage object and send more than just a message with Raygun.recordBreadcrumb(RaygunBreadcrumbMessage).
The structure of the type RaygunBreadcrumbMessage is as shown here:
RaygunBreadcrumbMessage({
required this.message,
this.category,
this.level = RaygunBreadcrumbLevel.info,
this.customData,
this.className,
this.methodName,
this.lineNumber,
});
copied to clipboard
Breadcrumbs can be cleared with Raygun.clearBreadcrumbs().
Getting/setting/cancelling the error before it is sent #
This provider has an onBeforeSend API to support accessing or mutating the candidate
error payload immediately before it is sent, or cancelling the sending action.
This is provided as the public callback Raygun.onBeforeSend,
which takes an OnBeforeSendCallback.
Example:
Raygun.onBeforeSend = (payload) {
// e.g. override the payload error message with a new message
payload.details.error!.message = 'New Error Message';

// important: return the payload to continue the sending action
return payload;
};
copied to clipboard
To cancel the sending action, return null:
Raygun.onBeforeSend = (payload) {
return null;
};
copied to clipboard
Set the Raygun.onBeforeSend to null to remove your custom callback:
Raygun.onBeforeSend = null;
copied to clipboard
Affected Customers #
Raygun supports tracking the unique customers who encounter bugs in your apps.
By default, a device-derived UUID is transmitted. You can also add the currently logged in customer's data like this using an object of type RaygunUserInfo:
Raygun.setUser(
RaygunUserInfo(
identifier: '1234',
firstName: 'FIRST',
fullName: 'LAST',
email: '[email protected]',
),
);
copied to clipboard
To clear the currently logged in customer, call setUser(null).
There is an additional convenience method that offers a shortcut to just track your customer by an indentifier only. If you use an email address to identify the user, please consider using setUser instead of setUserId as it would allow you to set the email address into both the identifier and email fields of the crash data to be sent.
Raygun.setUserId('1234');
copied to clipboard
Call with null to clear the user identifier: setUserId(null)
Custom endpoints #
Raygun supports sending data from Crash Reporting to your own endpoints. If you want to set custom endpoints, could can do so by setting them after you've initialised Raygun:
Raygun.setCustomCrashReportingEndpoint(url)
copied to clipboard
Please note that setting a custom endpoint will stop Crash Report or Real User Monitoring data from being sent to the Raygun backend.
Obfuscation #
Flutter supports code obfuscation with the --obfuscate parameter, this option generates symbol files that can be used to decode the obfuscated stack traces, as described in the section Obfuscate Dart code from the Flutter SDK.
Note that Flutter Web uses sourcemaps instead, which is described in the next section.
To decode obfuscated Flutter stacktraces with Raygun, you will have to copy the stacktrace into a file and run the flutter symbolize command manually. In the future, Raygun aims to support this functionality directly in the website.
For example, a file named stack.txt. It will look similar to this:
at *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** (file:///***:null)
at pid: 29207, tid: 29228, name 1.ui (unparsed:null)
at android arch: arm64 comp: yes sim: no (os::null)
at build_id: '63956a45f09b3f8410d244053eebd180' (unparsed:null)
at isolate_dso_base: 708882d000, vm_dso_base: 708882d000 (unparsed:null)
at isolate_instructions: 7088903b40, vm_instructions: 70888ed000 (unparsed:null)
at #00 abs 00000070889bcc93 virt 000000000018fc93 _kDartIsolateSnapshotInstructions+0xb9153 (unparsed:null)
at #01 abs 00000070889464fb virt 00000000001194fb _kDartIsolateSnapshotInstructions+0x429bb (unparsed:null)
... etc ...
copied to clipboard
Then, run the decode command passing in the copied stacktrace and the symbol file corresponding to the architecture. For example:
flutter symbolize -i stack.txt -d out/android/app.android-arm64.symbols
copied to clipboard
The decoded output will be similar to this:
at *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** (file:///***:null)
at pid: 29207, tid: 29228, name 1.ui (unparsed:null)
at android arch: arm64 comp: yes sim: no (os::null)
at build_id: '63956a45f09b3f8410d244053eebd180' (unparsed:null)
at isolate_dso_base: 708882d000, vm_dso_base: 708882d000 (unparsed:null)
at isolate_instructions: 7088903b40, vm_instructions: 70888ed000 (unparsed:null)
at #0 _MyAppState.build.<anonymous closure> (/[redacted]/raygun4flutter/example/lib/main.dart:89:17)
at #1 _InkResponseState.handleTap (//[redacted]/flutter/packages/flutter/lib/src/material/ink_well.dart:1170:21)
... etc ...
copied to clipboard
Flutter web source maps #
Flutter web applications use dart2js to produce a single JavaScript file main.dart.js.
However, when reporting errors to Raygun, the reported stack traces correspond to the JavaScript generated code and not the original Dart code.
Source maps help to convert generated JavaScript code back into Dart source code.
Raygun uses them to take obfuscated stack trace errors that point to generated JavaScript code and translate them to locations in Dart code.
To generate the Flutter web source maps, compile your project with the --source-maps option.
For example:
flutter build web --source-maps
copied to clipboard
This will generate the source map file, e.g. main.dart.js.map inside the build/web folder.
Then, upload this file to the Js Source Map Center in your Raygun project's Application Settings and configure them appropriately.
You can find more information regarding source maps within our documentation site - Source Maps for JavaScript.
Uploading source maps with Raygun CLI #
Raygun CLI is a command-line tool for Raygun.
Install with:
dart pub global activate raygun_cli
copied to clipboard
To upload Flutter web sourcemaps to Raygun, navigate to your project root and run the sourcemap command with the platform armument (-p) to flutter and set the uri, app-id and access token parameters.

uri is the full URI where your application main.dart.js will be installed to.
app-id the Application ID in Raygun.com.
token is an access token from https://app.raygun.com/user/tokens.

raygun-cli sourcemap -p flutter --uri=https://example.com/main.dart.js --app-id=APP_ID --token=TOKEN
copied to clipboard
The input-map argument is optional for Flutter web projects. raygun-cli will try to find the main.dart.js.map file in build/web/main.dart.js.map automatically.
For more information see raygun-cli on pub.dev
Comprehensive sample app #
For a working sample app across multiple platforms, check the Flutter project in the example directory.
Known issues #

setMaxReportsStoredOnDevice is not exposed and is currently set to 64.