BugSnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.
This documentation is for version 2 of the BugSnag Flutter library. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.
Configuration options are optional parameters to the start function:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
apiKey: 'your-api-key-here',
appVersion: '1.2.3-alpha',
);
The API key used for events sent to BugSnag.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
apiKey: 'your-api-key-here',
);
You can find your API key in Project Settings from your BugSnag dashboard.
Applies to iOS only.
Enables reporting of non-fatal app hangs from which your app recovered before being terminated by the user or the iOS watchdog.
By default this is set to the constant appHangThresholdFatalOnly, meaning that an error will only be sent to BugSnag if your app hang is fatal.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
appHangThresholdMillis: 5000,
);
If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.
This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
appType: 'lite',
);
The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.
BugSnag will automatically determine your app’s version.
On Android, the versionName field from your app’s manifest file is used.
On iOS and macOS, CFBundleShortVersionString from Info.plist is used.
If you’d like to override this you can set the appVersion configuration option:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
appVersion: '1.2.3-alpha',
);
By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
autoDetectErrors: false,
);
Setting autoDetectErrors to false will disable all automatic errors, regardless of the error types enabled by the Enabled Error Types configuration option.
By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
autoTrackSessions: false,
);
If you want control over what is deemed a session, you can switch off the automatic session tracking option and manage the session manually. See Capturing sessions for more information.
Applies to iOS only.
The bundle version of the application.
We’ll automatically set this from the CFBundleVersion value in your Info.plist file. If you’d like to override this you can set the Bundle Version configuration option:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
bundleVersion: '3.22.0',
);
The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
context: 'InitialTutorialStep',
);
Allows you to specify which events should be automatically discarded based on their errorClass.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
discardClasses: const {
'java.net.UnknownHostException',
'SIGPIPE',
},
);
By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
enabledBreadcrumbTypes: const {
BugsnagEnabledBreadcrumbType.navigation,
BugsnagEnabledBreadcrumbType.request,
},
);
Automatically captured breadcrumbs can be disabled as follows:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
enabledBreadcrumbTypes: const {},
);
The following automatic breadcrumb types can be enabled:
Error breadcrumbs (BugsnagEnabledBreadcrumbType.error) are left when an error event is sent to the BugSnag API.
Navigation breadcrumbs (BugsnagEnabledBreadcrumbType.navigation) are left for navigation-related notifications to track the user’s journey in the app.
Network request breadcrumbs (BugsnagEnabledBreadcrumbType.request) are left for network requests made by your app. See Customizing breadcrumbs for more information.
State breadcrumbs (BugsnagEnabledBreadcrumbType.state) are left for system broadcast events. For example: network connectivity changes, orientation changes, etc. See Automatically captured data for more information.
User breadcrumbs (BugsnagEnabledBreadcrumbType.user) are left when the user performs certain system operations. See Automatically captured data for more information.
BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
enabledErrorTypes: const BugsnagEnabledErrorTypes(
unhandledDartExceptions: false, // Exceptions in Dart
unhandledJvmExceptions: false, // Exceptions in Android JVM
crashes: false, // Native crashes
anrs: false, // Android Application Not Responding
appHangs: false, // iOS native hangs
thermalKills: false, // iOS thermal kills
ooms: false // iOS Out Of Memory
)
);
Setting the Auto Detect Errors configuration option to false will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes.
By default, BugSnag will be notified of events that happen in any releaseStage. Set this option if you would like to change which release stages notify BugSnag.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
enabledReleaseStages: const {'production', 'development', 'testing'},
);
By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.
If you are using BugSnag On-premise you’ll need to set these to your Event Server
and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking
will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
endpoints: const BugsnagEndpointConfiguration(
'https://notify.example.com', 'https://sessions.example.com'),
);
Declare feature flag and experiment usage.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
featureFlags: const [
BugsnagFeatureFlag('Checkout button color', 'Blue'),
BugsnagFeatureFlag('Special offer', 'Free Coffee'),
BugsnagFeatureFlag('New checkout flow'),
],
);
See the Feature flags & experiments guide for more information.
The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.
By default this value is 5000 milliseconds.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
launchDurationMillis: 0,
);
Events that occur during app launch will have their app.isLaunching property set to true.
Setting this to 0 will cause BugSnag to consider the app to be launching until markLaunchCompleted() has been called. See Identifying crashes at launch for further information.
Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.
By default, 50 breadcrumbs are stored; this can be amended up to a maximum of 100.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
maxBreadcrumbs: 75,
);
Sets the maximum number of events which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest events will be deleted.
By default, 32 events are stored.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
maxPersistedEvents: 50,
);
Sets the maximum number of sessions which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest sessions will be deleted.
By default, 128 sessions are stored.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
maxPersistedSessions: 50,
);
The maximum length of a string in metadata. To help avoid excessive event payload sizes, any strings exceeding this length will be truncated.
This limit defaults to 10,000 characters.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
maxStringValueLength: 5000,
);
Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
metadata: const {
'company': {
'name': 'Acme Co.',
'country': 'uk'
}
}
);
The top-level keys of the supplied map are section names that are displayed as tabs in the BugSnag dashboard.
Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
onError: [
(event) {
event.addMetadata('game', const {'current_score': 13});
return true;
},
],
);
Applies to Android only.
Sets the directory where BugSnag data, such as event and session payloads, are cached on disk. User information is also persisted here if the Persist User configuration option is true.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
persistenceDirectory: '/my-custom-dir',
);
The default directory for this property is Android’s cache directory.
If you change the value of the persistence directory between application launches, no attempt will be made to migrate data persisted from the original location. This may result in events and sessions not being delivered to BugSnag.
Set whether or not BugSnag should persist user information between application launches.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
persistUser: false,
);
By default persistUser is set to true.
If enabled then any user information set will be re-used until the user information is removed manually by calling setUser with null arguments.
Sets which package names BugSnag should consider as a part of the running application. We mark stacktrace lines as in-project if they originate from any of these packages and this allows us to improve the visual display of the stacktrace on the dashboard.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
projectPackages: BugsnagProjectPackages.withDefaults({'my_flutter_app'}),
);
By default, we attempt to make sensible inferences about which packages are in-project. To keep those defaults but also add other packages, pass the additional package names to BugsnagProjectPackages.withDefaults.
If you are building with --split-debug-info, the package name is not available and so you need pass it here. You also need to pass the names of any additional in-project Dart packages or if you have Android packages in native modules. You do not need to pass any additional iOS package names. For more information, see the Integration guide.
Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.
Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
redactedKeys: const {'credit_card_number'},
);
By default, redactedKeys is set to 'password'
Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
releaseStage: 'development',
);
This is automatically configured by the notifier to be “production” for apps built in release mode, otherwise it will be set to “development”.
You can control whether events are sent for specific release stages using the Enabled Release Stages configuration option.
Determines whether launch crashes should be sent synchronously whilst BugSnag starts.
If this option is enabled and the previous run terminated due to a crash during app launch, BugSnag will block the calling thread when it starts for up to 2 seconds while the crash report is sent.
This behavior is enabled by default.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
sendLaunchCrashesSynchronously: false,
);
Controls whether we should capture and serialize the state of all threads at the time of an exception.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
sendThreads: BugsnagThreadSendPolicy.unhandledOnly,
);
By default this option is set to BugsnagThreadSendPolicy.always. This can be set to BugsnagThreadSendPolicy.never to disable the sending of threads entirely or BugsnagThreadSendPolicy.unhandledOnly to only send threads for unhandled errors.
Internal errors are sent when an error is detected within BugSnag, for example when a crash report cannot be processed.
To prevent these from being sent:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
telemetry: const {BugsnagTelemetryType.usage}
);
Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:
We collect only bools, ints and enums. We do not collect any information personal to you or your users. The information is sent as part of error events; there is no additional network call made.
To prevent this from being sent:
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
telemetry: const {BugsnagTelemetryType.internalErrors}
);
Set global user data that you want to send with all captured events – see Adding user data for more information.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
user: BugsnagUser(id: '3', email: 'bugs.nag@bugsnag.com', name: 'Bugs Nag'),
);
Applies to Android only.
We’ll automatically pull the versionCode field from your app manifest file. If you’d like to override this you can set this option manually.
void main() => bugsnag.start(
runApp: () => runApp(const MyFlutterApp()),
versionCode: 123,
);