Configuration options

The Bugsnag client object 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 6 of the Bugsnag iOS notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Setting configuration options

Most configuration options can be set in your Info.plist file:

Set the apiKey in your Info.plist

Or in XML:

<key>bugsnag</key>
<dict>
    <key>apiKey</key>
    <string>YOUR-API-KEY</string>
</dict>

Bugsnag can then simply be started using:

[Bugsnag start];
Bugsnag.start()

Alternatively, configuration options can be specified in code by creating a BugsnagConfiguration object and passing it into the start method:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.appVersion = @"1.0.0-alpha";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.appVersion = "1.0.0-alpha"
Bugsnag.start(with: config)

loadConfig uses your Info.plist file to set initial configuration values, allowing you to augment and override the values before they are used to start Bugsnag. You can use the BugsnagConfiguration initalizer with an API key to avoid using the properties file.

Available options

addMetadata

Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addMetadata:@"Acme Co." withKey:@"name" toSection:@"account"];
[config addMetadata:@{ @"delivery": @"express", @"sale": @"spring" }
          toSection:@"basket"];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.addMetadata("Acme Co.", key: "name", section: "account")
config.addMetadata(["delivery": "express", "sale": "spring"],
                   section: "basket")
Bugsnag.start(with: config)

addOnBreadcrumb

Add callbacks to modify or discard breadcrumbs before they are recorded — see Customizing breadcrumbs for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnBreadcrumbBlock:^(BugsnagBreadcrumb *_Nonnull breadcrumb) {
    if ([breadcrumb.message isEqualToString:@"Noisy breadcrumb"]) {
        return NO; // ignore the breadcrumb
    } else {
        return YES; // capture the breadcrumb
    }
}];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.addOnBreadcrumb { (breadcrumb) -> Bool in
    if (breadcrumb.message == "Noisy Breadcrumb") {
        return false // ignore the breadcrumb
    } else {
        return true // capture the breadcrumb
    }
}
Bugsnag.start(with: config)

addOnSendError

Add callbacks to modify or discard error events before they are sent to Bugsnag — see Customizing error reports for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnSendErrorBlock:^BOOL (BugsnagEvent *event) {
    [event addMetadata:@"Acme Co." withKey:@"name" toSection:@"account"];
    [event addMetadata:@(YES) withKey:@"paying_customer" toSection:@"account"];

    // Return `NO` if you'd like to stop this error being reported
    return YES;
}];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.addOnSendError { (event) -> Bool in
    event.addMetadata("Acme Co.", key:"name", section:"account")
    event.addMetadata(true, key:"paying_customer", section:"account")

    // Return `false` if you'd like to stop this error being reported
    return true
}
Bugsnag.start(with: config)

addOnSession

Add callbacks to modify or discard sessions before they are sent to Bugsnag — see Capturing sessions for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnSessionBlock:^(BugsnagSession *session) {
    NSString *userId = [self getMyUserIdentifier]; // a custom user resolver
    [session setUser:userId withEmail:nil andName:nil];
    return YES; // Return false to discard
}];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.addOnSession { (session) -> Bool in
    let userId = getMyUserIdentifier() // a custom user resolver
    session.setUser(userId, withEmail: nil, andName: nil)
    return true // Return false to discard
}
Bugsnag.start(with: config)

apiKey

The API key used for events sent to Bugsnag.

let config = BugsnagConfiguration.loadConfig()
config.apiKey = "YOUR-OTHER-API-KEY";
Bugsnag.start(with: config)
BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.apiKey = @"YOUR-OTHER-API-KEY";
[Bugsnag startWithConfiguration:config];

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>apiKey</key>
    <string>YOUR-API-KEY</string>
</dict>

You can find your API key in Project Settings.

appType

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.appType = @"lite";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.appType = "lite";
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>appType</key>
    <string>lite</string>
</dict>

appVersion

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 set the version from the CFBundleShortVersionString value in your Info.plist file. If you’d like to override this you can set appVersion:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.appVersion = @"5.3.55";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.appVersion = "5.3.55"
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>appVersion</key>
    <string>"5.3.55"</string>
</dict>

The bundle version (based on CFBundleVersion) is also automatically included and can be overridden using the bundleVersion configuration option.

autoDetectErrors

By default, we will automatically notify Bugsnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.autoDetectErrors = NO;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.autoDetectErrors = false
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>autoDetectErrors</key>
    <false/>
</dict>

Setting autoDetectErrors to false will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes.

autoTrackSessions

By default, Bugsnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.autoTrackSessions = NO;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.autoTrackSessions = false
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>autoTrackSessions</key>
    <false/>
</dict>

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.

bundleVersion

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 bundleVersion:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.bundleVersion = @"3.22.0";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.bundleVersion = "3.22.0"
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>bundleVersion</key>
    <string>"3.22.0"</string>
</dict>

clearMetadata

Clears diagnostic metadata from being sent in subsequent events – see Customizing error reports for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config clearMetadataFromSection:@"account"];
// or
[config clearMetadataFromSection:@"account" withKey:@"name"];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.clearMetadata(section: "account")
// or
config.clearMetadata(section: "account", key: "name")
Bugsnag.start(with: config)

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.context = @"InitialTutorialStep";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.context = "InitialTutorialStep"
Bugsnag.start(with: config)

enabledBreadcrumbTypes

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.enabledBreadcrumbTypes = BSGEnabledBreadcrumbTypeNavigation
                                | BSGEnabledBreadcrumbTypeRequest;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.enabledBreadcrumbTypes = [.navigation, .request]
Bugsnag.start(with: config)

Automatically captured breadcrumbs can be disabled as follows:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.enabledBreadcrumbTypes = BSGEnabledBreadcrumbTypeNone;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.enabledBreadcrumbTypes = []
Bugsnag.start(with: config)

The following breadcrumb types can be enabled:

Captured errors

Error breadcrumbs (.error/BSGEnabledBreadcrumbTypeError) are left when an error event is sent to the Bugsnag API.

Console messages (React Native only)

Log breadcrumbs (.log/BSGEnabledBreadcrumbTypeLog) are left for each message logged to the console.

Navigation breadcrumbs (.navigation/BSGEnabledBreadcrumbTypeNavigation) are left for navigation-related notifications to track the user’s journey in the app.

State changes

State breadcrumbs (.state/BSGEnabledBreadcrumbTypeState) are left for system notifications. For example: network connectivity changes, orientation changes, etc. See Automatically captured data for more information.

User interaction

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

enabledErrorTypes

Bugsnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.enabledErrorTypes.cppExceptions = YES;
config.enabledErrorTypes.machExceptions = YES;
config.enabledErrorTypes.ooms = YES;
config.enabledErrorTypes.signals = YES;
config.enabledErrorTypes.unhandledExceptions = YES;
config.enabledErrorTypes.unhandledRejections = YES; // React Native only
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.enabledErrorTypes.cppExceptions = true
config.enabledErrorTypes.machExceptions = true
config.enabledErrorTypes.ooms = true
config.enabledErrorTypes.signals = true
config.enabledErrorTypes.unhandledExceptions = true
config.enabledErrorTypes.unhandledRejections = true // React Native only
Bugsnag.start(with: config)

OOMs are not reported when the debugger is attached.

Setting autoDetectErrors to false will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes.

enabledReleaseStages

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.enabledReleaseStages = [NSSet setWithArray:@[@"production", @"development", @"testing"]];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.enabledReleaseStages = ["production", "development", "testing"]
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>enabledReleaseStages</key>
    <array>
        <string>production</string>
    </array>
</dict>

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.endpoints = [[BugsnagEndpointConfiguration alloc] initWithNotify:@"https://notify.bugsnag.com"
                                                               sessions:@"https://sessions.bugsnag.com"];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.endpoints = BugsnagEndpointConfiguration(notify: "https://notify.bugsnag.com",
                                              sessions: "https://sessions.bugsnag.com")
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>endpoints</key>
    <dict>
        <key>notify</key>
        <string>https://notify.bugsnag.com</string>
        <key>sessions</key>
        <string>https://sessions.bugsnag.com</string>
    </dict>
</dict>

maxBreadcrumbs

Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.

By default, 25 breadcrumbs are stored; this can be amended up to a maximum of 100.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.maxBreadcrumbs = 50;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.maxBreadcrumbs = 50
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>maxBreadcrumbs</key>
    <integer>50</integer>
</dict>

onCrashHandler

Add a callback to be executed in the crashing context — see Crash-time callbacks for more information.

// Create crash handler
#import <Bugsnag/BSG_KSCrashReportWriter.h>

void HandleCrashedThread(const BSG_KSCrashReportWriter *writer) {
  // add metadata
  writer->beginObject(writer, "account");
  writer->addStringElement(writer, "name", "Acme Co.");
  writer->endContainer(writer);
  // possibly serialize data, call another crash reporter, ...
}
// Assign crash handler function to the configuration
BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.onCrashHandler = &HandleCrashedThread;
[Bugsnag startWithConfiguration:config];
// Assign crash handler function to the configuration
let config = BugsnagConfiguration.loadConfig()
config.onCrashHandler = HandleCrashedThread
Bugsnag.start(with: config)

All functions called from a signal handler must be asynchronous-safe. In particular, you should not use any Objective-C inside the onCrashHandler code.

persistUser

Set whether or not Bugsnag should persist user information between application sessions.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.persistUser = YES;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.persistUser = true
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>persistUser</key>
    <true/>
</dict>

redactedKeys

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.

The array can include both strings and regexes.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.redactedKeys = [NSSet setWithArray:@[@"password", @"credit_card_number"]];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.redactedKeys = ["password", "credit_card_number"]
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>redactedKeys</key>
    <array>
        <string>password</string>
        <string>credit_card_number</string>
    </array>
</dict>

By default, redactedKeys is set to "password".

releaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

This is automatically configured by the notifier to be “production”, unless DEBUG is defined during compilation in which case it will be set to “development”. If you wish to override this, you can do so by setting the releaseStage property manually:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.releaseStage = @"testing";
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.releaseStage = "testing"
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>releaseStage</key>
    <string>testing</string>
</dict>

sendThreads

Controls whether we should capture and serialize the state of all threads at the time of an exception.

By default sendThreads is set to Thread.ThreadSendPolicy.ALWAYS. This can be set to Thread.ThreadSendPolicy.NEVER to disable or Thread.ThreadSendPolicy.UNHANDLED_ONLY to only do so for unhandled errors.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.sendThreads = BSGThreadSendPolicyAlways;
// alternatively: config.sendThreads = BSGThreadSendPolicyUnhandledOnly;
//            or: config.sendThreads = BSGThreadSendPolicyNever;
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.sendThreads = .always
// alternatively: config.sendThreads = .unhandledOnly
//            or: config.sendThreads = .never
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>sendThreads</key>
    <string>always</string>
<!-- alternatively: <string>unhandledonly</string> -->
<!-- or           : <string>never</string> -->
</dict>

session

To customize the configuration or delegate used when sending error reports, create a custom NSURLSession (Objective-C) / URLSession (Swift).

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.session = [NSURLSession sessionWithConfiguration:myConfig];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.session = URLSession(configuration:myConfig)
Bugsnag.start(with: config)

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

Pinning certificates with RNPinnedCertValidator

To pin your certificates, we recommend that you implement NSURLConnectionDelegate using the RNPinnedCertValidator library, as shown in the example below.

- (void)connection:(NSURLConnection *)connection
willSendRequestForAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge {

    // ensures that all requests pin SSL certificates.
    RNPinnedCertValidator *validator =
    [[RNPinnedCertValidator alloc] initWithCertificatePath:@"my_cert.cer"];
    [validator validateChallenge:challenge];
}
func connection(_ connection: NSURLConnection,
willSendRequestForAuthenticationChallenge: URLAuthenticationChallenge) {

    // ensures that all requests pin SSL certificates.
    let validator = RNPinnedCertValidator("my_cert.cer")
    validator.validate(challenge)
}

setUser

Set global user data that you want to send with all captured events – see Adding user data for more information.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config setUser:@"3" withEmail:@"bugs.nag@bugsnag.com" andName:@"Bugs Nag"];
[Bugsnag startWithConfiguration:config];
let config = BugsnagConfiguration.loadConfig()
config.setUser("3", withEmail: "bugs.nag@bugsnag.com", andName: "Bugs Nag")
Bugsnag.start(with: config)