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:

BugsnagConfiguration *config = [BugsnagConfiguration new];
config.apiKey = @"YOUR-API-KEY";
// ... customize other config properties as needed
[Bugsnag startBugsnagWithConfiguration:config];

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.

apiKey

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

config.apiKey = @"YOUR-API-KEY";

config.apiKey = "YOUR-API-KEY"

appVersion

If you want to override the version number of your application you can set appVersion. This defaults to the value of CFBundleShortVersionString in your app’s Info.plist file. The build version (based on CFBundleVersion) is also automatically included separately (not overridable).

config.appVersion = @"5.3.55";

config.appVersion = "5.3.55"

automaticallyCollectBreadcrumbs

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 = NO;

config.automaticallyCollectBreadcrumbs = false

autoNotify

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 = NO;

config.autoNotify = false

beforeSendBlocks

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 addBeforeSendBlock:^bool (NSDictionary *_Nonnull rawEventData,
                                  BugsnagCrashReport *report) {
    return ![report.errorClass isEqualToString:@"Failed receipt validation"];
}];

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

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

beforeSendBlocks will be invoked on a dedicated background queue, which will be different from the queue where the block was originally added.

context

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. By default this is set this to the top most UIViewController, code location, or method, but it can be overriden by using this property:

config.context = @"MyUIViewController";

config.context = "MyUIViewController"

notifyReleaseStages

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"];

config.notifyReleaseStages = ["production"]

notifyURL

This value returns the endpoint to which error reports are sent. It is strongly recommended that you set this value via the setEndpoints method.

onCrashHandler

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 BSG_KSCrashReportWriter *writer) {
  // possibly serialize data, call another crash reporter
  writer->addJSONElement(writer, "dessertMap", dessertMapObj);
}

// Assign crash handler function to the configuration
config.onCrashHandler = &HandleCrashedThread;

// Assign crash handler function to the configuration
config.onCrashHandler = HandleCrashedThread

releaseStage

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";

config.releaseStage = "development"

reportOOMs

BugSnag automatically detects and captures likely out of memory app termination events on iOS. Set this configuration option to false to disable reporting out of memory events.

config.reportOOMs = NO;

config.reportOOMs = false

resumeSession

Resumes a session which has previously been stopped, or starts a new session if none exists. If a session has already been resumed or started and has not been stopped, calling this method will have no effect. You should disable automatic session tracking via shouldAutoCaptureSessions if you call this method.

It’s important to note that sessions are stored in memory for the lifetime of the application process and are not persisted on disk. Therefore calling this method on app startup would start a new session, rather than continuing any previous session.

You should call this at the appropriate time in your application when you wish to resume a previously started session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score.

[Bugsnag resumeSession];

Bugsnag.resumeSession()

Also see startSession and stopSession.

session

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

config.session = [NSURLSession sessionWithConfiguration:myConfig];

config.session = URLSession(configuration:myConfig)

This property can be used when pinning custom certificates or to add delegate methods to the request lifecycle. 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)
}

sessionURL

This value returns the endpoint to which tracked sessions reports are sent. It is strongly recommended that you set this value via the setEndpoints method.

setBreadcrumbCapacity

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

[Bugsnag setBreadcrumbCapacity:30];

Bugsnag.setBreadcrumbCapacity(30)

setEndpoints

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.

[config setEndpointsForNotify:@"http://notify.example.com"
                     sessions:@"http://sessions.example.com"];

config.setEndpoints(notify: "http://notify.example.com",
                  sessions: "http://sessions.example.com")

shouldAutoCaptureSessions

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

config.shouldAutoCaptureSessions = NO;

config.shouldAutoCaptureSessions = false

If you want control over what is deemed a session, you can switch off automatic session tracking with the shouldAutoCaptureSessions option, and call startSession() when appropriate for your application.

[Bugsnag startSession];

Bugsnag.startSession()

startSession

Starts tracking a new session. You should disable automatic session tracking via shouldAutoCaptureSessions if you call this method.

You should call this at the appropriate time in your application when you wish to start a session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score. This will start a new session even if there is already an existing session; you should call resumeSession if you only want to start a session when one doesn’t already exist.

[Bugsnag startSession];

Bugsnag.startSession()

Also see resumeSession and stopSession.

stopSession

Stops tracking a session. You should disable automatic session tracking via shouldAutoCaptureSessions if you call this method.

You should call this at the appropriate time in your application when you wish to stop a session. Any subsequent errors which occur in your application will still be reported to BugSnag but will not count towards your application’s stability score. This can be advantageous if, for example, you do not wish the stability score to include crashes in a background service.

[Bugsnag stopSession];

Bugsnag.stopSession()

Also see resumeSession and startSession.

user

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:@"user@email.com"];

config.setUser("userId", withName:"User Name", andEmail:"user@example.com")

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.