Raygun4Flutter adds a Flutter plugin to your app that captures and handles errors, and reports the error information to your Raygun Crash Reporting dashboard.

The plugin internally uses Raygun's Android and iOS providers to report crashes and custom errors to Raygun.

Requirements

• Dart SDK 2.12+

As of release 1.0.0, Raygun4Flutter is built entirely in Dart and no longer relies on the native providers Raygun4Android and Raygun4Apple. We've also started to improve support for Flutter Desktop and Web. We'd appreciate any feedback on Github.

Installation

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: [refer to Dart package for latest version]

Raygun4Flutter Dart package

Alternatively, your editor might support flutter pub get. To determine this, check the docs for your editor.

In your Dart code, you can now use:

import 'package:raygun4flutter/raygun4flutter.dart';

Platform-specific notes

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 need to track crash reports across various layers and parts of your application written in different technologies, you might need to implement the relevant native providers for Android, iOS or other platforms.

Android

In your app's AndroidManifest.xml (usually located in your Flutter project's /android/src/main directory), make sure you have granted Internet permissions.

Beneath the <manifest> element (if it doesn't exist already) add:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Setup and usage

Initialisation and version tracking

Call Raygun.init() with an API key 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:'paste_your_api_key_here');
  }

}

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:'paste_your_api_key_here',version:'1.4.5');

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 capture errors inside Flutter, you need to add a custom FlutterError.onError handler to your main method. This 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,
    );
};

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(MyApp());
}, (Object error, StackTrace stackTrace) {
  Raygun.sendException(
    error: error, 
    stackTrace: stackTrace
    );
});

Release

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

Customers

Raygun supports tracking of the unique customers who encounter bugs in your apps.

By default, Raygun will transmit a device-derived UUID. You can also add the data of the currently signed-in customer using an object of type RaygunUserInfo:

Raygun.setUser(
RaygunUserInfo(
identifier: '1234',
firstName: 'FIRST',
fullName: 'LAST',
email: 'test@example.com',
),
);

To clear the currently logged-in customer, call setUser(null).

There's an additional convenience method that offers a shortcut to track your customer by an identifier only. If you use an email address to identify the user, consider using setUser instead of setUserId, as this will allow you to set the email address into both the identifier and email fields of the crash data.

Raygun.setUserId('1234');

Call with null to clear the user identifier: setUserId(null)

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);
}

All arguments except error are optional. This method is mainly a convenience wrapper around the more customisable .sendCustom() method which obtains the class name and the message from the error object.

Sending custom errors manually

Call Raygun.sendCustom(className, message, tags, customData, stackTrace) to send custom errors to Raygun with your own customised className and message. As with .sendException(), tags, customData and stackTrace are optional.

For example:

Raygun.sendCustom(
  className: 'MyApp',
  reason: 'test error message',
  tags: ['API','Tag2'],
  customData: {
    'custom1': 'value',
    'custom2': 42,
  },
  stackTrace: StackTrace.current,
);

Advanced features

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']);

Custom data

Raygun.setCustomData() sets a global map of key-value pairs that, similar to tags, will be logged with every exception. These will be merged with other custom data passed into manually created crash reports via sendException() and sendCustom().

Raygun.setCustomData({
  'custom1': 'value',
  'custom2': 42,
});

Breadcrumbs

Sending breadcrumbs to Raygun will provide additional information to help investigate 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');

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,
});

Custom endpoints

Raygun supports sending data from Crash Reporting to your own endpoints. If you want to set custom endpoints, you can do so after you've initialised Raygun:

Raygun.setCustomCrashReportingEndpoint(url)

Please note that setting a custom endpoint will stop Crash Report or Real User Monitoring data from being sent to the Raygun backend.