Docs Platforms tvOS Configuration
bugsnag.com Start Free Trial

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 tvOS 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

Many 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>

The Bugsnag client 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 to the client:

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 initializer with an API key to avoid using the properties file.

Available options

addFeatureFlag

Declare a single feature flag or experiment with variant as an optional second parameter.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addFeatureFlagWithName:@"Checkout button color" variant:@"Blue"];
[config addFeatureFlagWithName:@"New checkout flow"];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.addFeatureFlag(name: "Checkout button color", variant: "Blue")
config.addFeatureFlag(name: "New checkout flow")
Bugsnag.start(with: config)

See the Feature flags & experiments guide for more information.

addFeatureFlags

Declare multiple feature flags or experiments.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addFeatureFlags:@[
    [BugsnagFeatureFlag flagWithName:@"Checkout button color" variant:@"Blue"],
    [BugsnagFeatureFlag flagWithName:@"Special offer" variant:@"Free Coffee"],
    [BugsnagFeatureFlag flagWithName:@"New checkout flow"]]];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.addFeatureFlags([
    BugsnagFeatureFlag(name: "Checkout button color", variant: "Blue"),
    BugsnagFeatureFlag(name: "Special offer", variant: "Free Coffee"),
    BugsnagFeatureFlag(name: "New checkout flow")])
Bugsnag.start(with: config)

See the Feature flags & experiments guide for more information.

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-API-KEY";
Bugsnag.start(with: config)

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.apiKey = @"YOUR-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 from your BugSnag dashboard.

appHangThresholdMillis

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 BugsnagAppHangThresholdFatalOnly, meaning that an error will only be sent to BugSnag if your app hang is fatal.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];

// Configure an app hang threshold to enable non-fatal app hangs
config.appHangThresholdMillis = 5000;

[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()

// Configure an app hang threshold to enable non-fatal app hangs
config.appHangThresholdMillis = 5000

Bugsnag.start(with: config)

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.

attemptDeliveryOnCrash

Whether BugSnag should try to send crashing errors prior to app termination.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.attemptDeliveryOnCrash = YES;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.attemptDeliveryOnCrash = true
Bugsnag.start(with: config)

Delivery will only be attempted for uncaught Objective-C exceptions, and while in progress will block the crashing thread for up to 3 seconds. Delivery should be considered unreliable due to the necessary short timeout and unreliable state of the app following an exception. If delivery fails prior to termination, it will be reattempted at next launch (the default behavior).

This feature is disabled by default and its use is discouraged because it:

  • may cause the app to hang while delivery occurs and impact the hang rate reported in Xcode Organizer
  • will result in duplicate error reports in your dashboard if the app terminates before the report can be confirmed as sent
  • may prevent other crash reporters from detecting or reporting a crash.

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 = @"5.3.55.2";
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.bundleVersion = "5.3.55.2"
Bugsnag.start(with: config)

Or in your Info.plist:

<key>bugsnag</key>
<dict>
    <key>bundleVersion</key>
    <string>5.3.55.2</string>
</dict>

clearFeatureFlag

Remove a single feature flag or experiment.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config clearFeatureFlagWithName:@"Checkout button color"];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.clearFeatureFlag(name: "Checkout button color")
Bugsnag.start(with: config)

See the Feature flags & experiments guide for more information.

clearFeatureFlags

Remove all feature flags and experiments.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config startWithConfiguration:config];
[Bugsnag clearFeatureFlags];

let config = BugsnagConfiguration.loadConfig()
config.clearFeatureFlags()
Bugsnag.start(with: config)

See the Feature flags & experiments guide for more information.

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)

discardClasses

Allows you to specify which events should be automatically discarded based on their errorClass.

Accepts both strings and regexes, and comparisons are case sensitive.

OnError / OnSendError blocks will not be called for discarded events.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.discardClasses = [[NSSet setWithObjects:@"SIGPIPE", [NSRegularExpression
    regularExpressionWithPattern:@"NS.*Exception" options:0 error:nil], nil];
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.discardClasses = try? ["SIGPIPE", NSRegularExpression(pattern: "NS.*Exception")]
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 automatic 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.

Network Requests

Request breadcrumbs (.request/BSGBreadcrumbTypeRequest) are left when a network request is made, and the BugsnagNetworkRequestPlugin is enabled.

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.appHangs = YES;
config.enabledErrorTypes.cppExceptions = YES;
config.enabledErrorTypes.machExceptions = YES;
config.enabledErrorTypes.ooms = YES;
config.enabledErrorTypes.signals = YES;
config.enabledErrorTypes.thermalKills = YES;
config.enabledErrorTypes.unhandledExceptions = YES;
config.enabledErrorTypes.unhandledRejections = YES; // React Native only
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.enabledErrorTypes.appHangs = true
config.enabledErrorTypes.cppExceptions = true
config.enabledErrorTypes.machExceptions = true
config.enabledErrorTypes.ooms = true
config.enabledErrorTypes.signals = true
config.enabledErrorTypes.thermalKills = 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>
        <string>development</string>
        <string>testing</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>

launchDurationMillis

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.launchDurationMillis = 0;
[Bugsnag startWithConfiguration:config];

// Once your app has finished launching;
[Bugsnag markLaunchCompleted];

let config = BugsnagConfiguration.loadConfig()
config.launchDurationMillis = 0
Bugsnag.start(with: config)

// Once your app has finished launching;
Bugsnag.markLaunchCompleted()

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 Bugsnag.markLaunchCompleted() has been called.

maxBreadcrumbs

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

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

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.maxBreadcrumbs = 75;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.maxBreadcrumbs = 75
Bugsnag.start(with: config)

Or in your Info.plist:

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

If a payload is greater than the 1MB upload limit, when possible breadcrumbs will be dropped (oldest first) until the size is reduced below the limit.

maxPersistedEvents

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.maxPersistedEvents = 50;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.maxPersistedEvents = 50
Bugsnag.start(with: config)

maxPersistedSessions

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.maxPersistedSessions = 50;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.maxPersistedSessions = 50
Bugsnag.start(with: config)

maxStringValueLength

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.maxStringValueLength = 5000;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.maxStringValueLength = 5000
Bugsnag.start(with: config)

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)

onCrashHandler must be implemented in C and call only asynchronous-safe functions because it may be called from a signal handler. You must not use any Objective-C or Swift.

persistUser

Set whether or not BugSnag should persist user information between application launches.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.persistUser = NO;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.persistUser = false
Bugsnag.start(with: config)

Or in your Info.plist:

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

By default persistUser is set to true.

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, 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.

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

Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).

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>

You can control whether events are sent for specific release stages using the enabledReleaseStages option.

reportBackgroundAppHangs

Enables reporting of app hangs that occur while the app is in the background.

By default this is set to false, so that these app hangs will be ignored.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.reportBackgroundAppHangs = YES;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.reportBackgroundAppHangs = true
Bugsnag.start(with: config)

This option is disabled by default as some system functions can cause hangs to occur when apps move into the background state.

For example, CABackingStoreCollectBlocking() has been observed to hang for more than 2 seconds while cleaning up graphics resources on some devices.

sendLaunchCrashesSynchronously

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.

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
// To prevent sending launch crashes synchronously;
config.sendLaunchCrashesSynchronously = NO;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
// To prevent sending launch crashes synchronously;
config.sendLaunchCrashesSynchronously = false
Bugsnag.start(with: config)

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)

telemetry

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

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.telemetry &= ~BSGTelemetryInternalErrors;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.telemetry.remove(.internalErrors)
Bugsnag.start(with: config)

Usage

Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:

  • when your config differs from the defaults
  • BugSnag functionality utilized

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:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
config.telemetry &= ~BSGTelemetryUsage;
[Bugsnag startWithConfiguration:config];

let config = BugsnagConfiguration.loadConfig()
config.telemetry.remove(.usage)
Bugsnag.start(with: config)