Configuration options

Bugsnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.

Setting configuration options

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

Available options

API Key

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.

App Hang Threshold

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

The threshold configured for non-fatal hangs will also be applied to fatal hangs.

App Type

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

App Version

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

Auto Detect Errors

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.

Auto Track Sessions

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.

Bundle Version

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

Context

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

Discard Classes

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

Enabled Breadcrumb Types

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:

Captured errors

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 requests

Network request breadcrumbs (BugsnagEnabledBreadcrumbType.request) are left for network requests made by your app. See Customizing breadcrumbs for more information.

State changes

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 interaction

User breadcrumbs (BugsnagEnabledBreadcrumbType.user) are left when the user performs certain system operations. See Automatically captured data for more information.

Enabled Error Types

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.

Enabled Release Stages

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

Endpoints

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

Feature Flags

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.

Launch Duration

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.

Max Breadcrumbs

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

Max Persisted Events

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

Max Persisted Sessions

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

Metadata

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.

On Error Callbacks

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

Persistence Directory

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.

Persist User

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.

Project Packages

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.

Redacted Keys

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, this array contains 'password'. Be aware that if you supply a new value, it will replace the default, so include 'password' in your own array 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'

Release Stage

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.

Send Launch Crashes Synchronously

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

Send Threads

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.

User

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

Version Code

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