Configuration options

Bugsnag provides several options to customize behavior during initialization. To start Bugsnag with a configuration, create the configuration object, update the properties as needed, and call the start method:

let config = BugsnagConfiguration()
config.apiKey = "YOUR-API-KEY"
// ... customize other config properties as needed
Bugsnag.start(with: config)

The complete list of available properties is available below.


Your Integration API Key, available on your Bugsnag dashboard under “Settings”

config.apiKey = "YOUR-API-KEY"


If you want to manually track in which versions of your application each exception happens, you can set appVersion.

config.appVersion = "5.3.55"


By default, we will automatically add breadcrumbs for common application events, such as application launch, entering the background, and windows becoming visible or hidden. To disable this behavior, set this property to false:

config.automaticallyCollectBreadcrumbs = false


By default, we will automatically notify Bugsnag of any fatal exceptions in your application. If you want to stop this from happening, you can set autoNotify to false:

config.autoNotify = false


When a manual notification is triggered or an app first launches after a crash, crash reports are sent to Bugsnag. The rawEventData parameter includes any custom data attached within an onCrashHandler.

To prevent a report from being sent, return false from the block.

NOTE: Segmentation faults and other similar crashes cannot be caught within handlers.

config.add { (rawData, report) -> Bool in
    return report.errorClass != "Failed receipt validation"

For a list of all properties available to be modified, see The report object.


Bugsnag uses the concept of “contexts” to help display and group your errors. Contexts represent what was happening in your application at the time an error occurs. The Notifier will set this to be the top most UIViewController, but if in a certain case you need to override the context, you can do so using this property:

config.context = "MyUIViewController"


By default, we notify Bugsnag of all exceptions that happen in your app. If you would like to change which release stages notify Bugsnag of exceptions you can set the notifyReleaseStages property:

config.notifyReleaseStages = ["production"]


By default Bugsnag sends reports to if you need to change this you can do so by starting Bugsnag with a different configuration object.

config.notifyURL = URL(string:"")


When a crash occurs in an application, information about the runtime state of the application is collected and prepared to be sent to Bugsnag on the next launch. The onCrashHandler hook allows you to execute additional code after the crash report has been written. This data is available for inspection after the next launch during the beforeSendBlocks phase.

NOTE: All functions called from a signal handler must be asynchronous-safe. This excludes any Objective-C, in particular.

// Create crash handler
void HandleCrashedThread(const KSCrashReportWriter *writer) {
  // possibly serialize data, call another crash reporter
  writer->addJSONElement(writer, "dessertMap", dessertMapObj);
// Assign crash handler function to the configuration
config.onCrashHandler = HandleCrashedThread


In order to distinguish between errors that occur in different stages of the application release process a release stage is sent to Bugsnag when an error occurs. This is automatically configured by the notifier to be “production”, unless DEBUG is defined during compilation. In this case it will be set to “development”. If you wish to override this, you can do so by setting the releaseStage property manually:

config.releaseStage = "development"


To customize the configuration or delegate used when sending error reports, create a custom URLSession.

config.session = URLSession(configuration:myConfig)

This property can be used when pinning custom certificates or to add delegate methods to the request lifecycle.


In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard. To set an identifier for a user, use the user property, which also stores other common fields:

config.setUser("userId", withName:"User Name", andEmail:"")

By default, Bugsnag sends a device- and vendor-specific identifier assigned as the userId for each device. The user ID, email, and name are searchable on the Bugsnag dashboard.