Upgrading Guide

Upgrade from 5.X to 6.X

This version contains many breaking changes. It is part of an effort to unify our notifier libraries across platforms, making the user interface more consistent, and implementations better on multi-layered environments where multiple Bugsnag libraries need to work together (such as React Native).

Key points

Several configuration options have been renamed and can now load configuration options from your Info.plist file, simplifying Bugsnag initialization. (See docs: iOS | macOS | tvOS.)
The BugsnagEvent class replaces BugsnagCrashReport and now contains all data that will be sent to your Bugsnag dashboard with typed fields, rather than dictionary fields. (See docs: iOS | macOS | tvOS.)
Callback blocks have been expanded to breadcrumbs (see docs: iOS | macOS | tvOS.) and sessions (see docs: iOS | macOS | tvOS.)

More details of these changes can be found below and full documentation is available online: iOS | macOS | tvOS.

Bugsnag Client

Starting Bugsnag

You can now start Bugsnag using your Info.plist with configuration values, including your API key. The simplest start-up code is therefore:

[Bugsnag start];

or

Bugsnag.start()

With an entry in your Info.plist file:

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

You can add further configuration options to your Info.plist or construct a BugsnagConfiguration to set further options in code. For full details, see the online docs: iOS | macOS | tvOS.

Additions

The following functions have been added to the Bugsnag client:

Property/Method	Usage
`addOnBreadcrumb` / `removeOnBreadcrumb` `addOnBreadcrumbBlock` / `removeOnBreadcrumbBlock`	Add/remove callbacks to modify or discard breadcrumbs before they are recorded. (See docs: iOS \| macOS \| tvOS.)
`addMetadata:metadata:toSection` / `addMetadata(metadata:section)`	Adds a dictionary of metadata to a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`getMetadataFromSection` / `getMetadata(section)` `getMetadataFromSection:withKey` / `getMetadata(section:key)`	Retrieves previously set metadata from a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`setUser:withEmail:andName` / `setUser(_:email:name)`	Sets the active user for the app for future events. (See docs: iOS \| macOS \| tvOS.)

Changes

The following changes have been made to the Bugsnag client:

v5.x API	v6.x API
`addAttribute:withValue:toTabWithName:` / `addAttribute(attributeName:withValue:toTabName)`	`addMetadata:withKey:toSection:` / `addMetadata(metadata:key:section)`
`clearTabWithName` / `clearTab(withName:)`	`clearMetadataFromSection` / `clearMetadata(section:)`
`startBugsnagWithApiKey`	`startWithApiKey`
`startBugsnagWithConfiguration`	`startWithConfiguration`
`stopSession`	`pauseSession`

Deprecations

The following properties/methods have been removed from the Bugsnag client:

v5.x API	v6.x API
`BugsnagSeverityError`	Deprecated - no longer public API.
`BugsnagSeverityWarning`	Deprecated - no longer public API.
`BugsnagSeverityInfo`	Deprecated - no longer public API.
`clearBreadcrumbs`	Deprecated in favor of `OnBreadcrumb` callback blocks. (See docs: iOS \| macOS \| tvOS.)
`configuration`	Deprecated - no longer public API.
`notify:withData:` / `notify(exception:withData)`	Use `notify:block:` / `notify(exception:block:)` to add data in a block. (See docs: iOS \| macOS \| tvOS.)
`notify:withData:atSeverity:` / `notify(exception:withData:atSeverity:)`	Use `notify:block:` / `notify(exception:block:)` to add data and set severity in a block. (See docs: iOS \| macOS \| tvOS.)
`payloadDateFormatter`	Deprecated - no longer public API.
`setBreadcrumbCapacity`	Now set in `BugsnagConfiguration`: `maxBreadcrumbs`.

Configuration

Additions

The following options have been added to the BugsnagConfiguration class:

Property/Method	Usage
`addOnBreadcrumbBlock` / `addOnBreadcrumb`	Add callbacks to modify or discard breadcrumbs before they are recorded. (See docs: iOS \| macOS \| tvOS.)
`addMetadata:metadata:toSection` / `addMetadata(metadata:section)`	Adds a dictionary of metadata to a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`clearMetadataFromSection` / `clearMetadata(section)` `clearMetadataFromSection:withKey` / `clearMetadata(section:key)`	Removes previously set metadata from a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`getMetadataFromSection` / `getMetadata(section)` `getMetadataFromSection:withKey` / `getMetadata(section:key)`	Retrieves previously set metadata from a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`maxBreadcrumbs`	Sets the maximum number of breadcrumbs which will be stored. (See docs: iOS \| macOS \| tvOS.)
`persistUser`	Set whether or not Bugsnag should persist user information between application sessions. (See docs: iOS \| macOS \| tvOS.)
`redactedKeys`	Sets which values should be removed from any `Metadata` objects before sending them to Bugsnag. (See docs: iOS \| macOS \| tvOS.)
`removeOnBreadcrumbBlock` / `removeOnBreadcrumb`	Remove callbacks that modify or discard breadcrumbs before they are recorded. (See docs: iOS \| macOS \| tvOS.)
`sendThreads`	Controls whether we should capture and serialize the state of all threads at the time of an exception. (See docs: iOS \| macOS \| tvOS.)

Note: Most configuration options can now be set in your Info.plist file. (See docs: iOS | macOS | tvOS.)

Changes

The following changes have been made to the BugsnagConfiguration class:

v5.x API	v6.x API
`autoCaptureSessions`	`autoTrackSessions`
`automaticallyCollectBreadcrumbs`	`enabledBreadcrumbTypes` (See docs: iOS \| macOS \| tvOS.)
`autoNotify`	`autoDetectErrors`
`beforeSendBlocks`	`addOnSendError` / `addOnSendErrorBlock` `removeOnSendErrorBlock` / `removeOnSendError`
`beforeSessionBlocks`	`addOnSession` / `addOnSessionBlock` `removeOnSessionBlock` / `removeOnSession`
`currentUser`	`user`
`metadata`	`addMetadata` / `clearMetadata` / `getMetadata`
`notifierType`	`appType`
`notifyReleaseStages`	`enabledReleaseStages`
`notifyURL`	`setEndpoints(BugsnagEndpointConfiguration)` (See docs: iOS \| macOS \| tvOS.)
`reportOOMs`	`enabledErrorTypes` (See docs: iOS \| macOS \| tvOS.)
`sessionURL`	`setEndpoints(BugsnagEndpointConfiguration)` (See docs: iOS \| macOS \| tvOS.)
`setEndpointsForNotify:sessions` / `setEndpoints(notify: sessions)`	`setEndpoints(BugsnagEndpointConfiguration)` (See docs: iOS \| macOS \| tvOS.)
`shouldAutoCaptureSessions`	`autoTrackSessions`

Note: OnSendError blocks now take a BugsnagEvent parameter (see below) only. If you are setting an onCrashHandler block to add crash-time data (see docs: iOS | macOS | tvOS) you must ensure the extra data is added as a string:object dictionary-like entry. This data will then be available as metadata in the BugsnagEvent.

Deprecations

The following properties/methods have been removed from the BugsnagConfiguration class:

v5.x API	v6.x API
`addBeforeNotifyHook`	Deprecated in favor of callback block argument to `Bugsnag.notify`. (See docs: iOS \| macOS \| tvOS.)
`breadcrumbs`	Deprecated in favor of `OnBreadcrumb` callback blocks. (See docs: iOS \| macOS \| tvOS.)
`config`	Deprecated - no longer public API.
`codeBundleId`	Deprecated - no longer public API.
`errorApiHeaders`	Deprecated - no longer public API.
`reportBackgroundOOMs`	Deprecated feature.
`sessionApiHeaders`	Deprecated - no longer public API.
`shouldSendReports`	Deprecated - no longer public API.

Metadata

Metadata should be managed through the Bugsnag client for future events or in a BugsnagEvent in a callback, therefore direct access to the BugsnagMetadata is no longer part of the public API.

(See docs: iOS | macOS | tvOS.)

Breadcrumbs

Additions

See addOnBreadcrumb for adding callbacks to access/amended data in the BugsnagBreadcrumb object that is about to be recorded.

(See docs: iOS | macOS | tvOS.)

Changes

The following changes have been made to the BugsnagBreadcrumb class:

v5.x API	v6.x API
`name`	`message`

Deprecations

The following properties/methods have been removed:

v5.x API	v6.x API
`BugsnagBreadcrumb` constructors	Deprecated - no longer public API.
`BugsnagBreadcrumbs`	Deprecated - no longer public API.

Events (`BugsnagCrashReport`)

BugsnagCrashReport is now called BugsnagEvent and contains all the data representing the error that's been captured for access and/or mutation in callbacks.

Additions

The following options have been added to the BugsnagEvent class:

Property/Method	Usage
`addMetadata:metadata:toSection` / `addMetadata(metadata:section)`	Adds a dictionary of metadata to a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`clearMetadataFromSection` / `clearMetadata(section)` `clearMetadataFromSection:withKey` / `clearMetadata(section:key)`	Removes previously set metadata from a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`getMetadataFromSection` / `getMetadata(section)` `getMetadataFromSection:withKey` / `getMetadata(section:key)`	Retrieves previously set metadata from a section, shown as a tab on the Bugsnag dashboard. (See docs: iOS \| macOS \| tvOS.)
`originalError`	The original object that caused the error in your application. (See docs: iOS \| macOS \| tvOS.)
`unhandled`	Whether the error was detected automatically by Bugsnag or reported manually via notify/notifyError. (See docs: iOS \| macOS \| tvOS.)
`user` / `setUser:withEmail:andName` / `setUser(_:email:name)`	The user of the app when the event occurred. (See docs: iOS \| macOS \| tvOS.)

Changes

Event data is now made available as structured classes on the device, app, errors and threads fields on the BugsnagEvent, previously this was included in undocumented NSDictionary data. (See docs: iOS | macOS | tvOS.)

Each event is now also delivered in a separate request to avoid exceeding Bugsnag's request payload size limit in extreme scenarios.

In addition:

v5.x API	v6.x API
`addAttribute:withValue:toTabWithName:` / `addAttribute(attributeName:withValue:toTabName)`	`addMetadata:withKey:toSection:` / `addMetadata(metadata:key:section)`

Deprecations

The following properties/methods have been removed from the BugsnagEvent (previously BugsnagCrashReport) class:

v5.x API	v6.x API
`attachCustomStacktrace:type:`	Deprecated - no longer public API.
`BSGParseSeverity`	Deprecated - no longer public API.
`BSGFormatSeverity`	Deprecated - no longer public API.
`depth`	Deprecated - no longer public API.
`enhancedErrorMessageForThread`	Deprecated - no longer public API.
`error`	Deprecated - no longer public API.
`handledState`	Deprecated in favor of `unhandled` property. (See docs: iOS \| macOS \| tvOS.)
`enabledReleaseStages`	Deprecated - no longer public API.
`isIncomplete`	Deprecated feature.
`overrides`	Deprecated - no longer public API.
`serializableValueWithTopLevelData`	Deprecated - no longer public API.
`shouldBeSent`	Deprecated - no longer public API.
`toJson`	Deprecated - no longer public API.

Depth Replacement

The depth property was removed in v6.x of the bugsnag-cocoa notifier. To reproduce this behaviour, you can use a callback to modify the stacktrace. The functions below will reproduce this behaviour:

⚠️ This can only be achieved using bugsnag-cocoa v6.0.1 and above, as the stacktrace array was previously readonly.

Using Swift, create a function as follows:

func bugsnagStacktraceDepth(event: BugsnagEvent, depth: Int) -> [BugsnagStackframe] {
    if depth > 0 && depth <= event.errors[0].stacktrace.count { /// Check the depth is in a usable range
        for _ in 0...(depth - 1) {
            /// always trim from the top of the stacktrace (index 0),
            /// `.stacktrace` is re-indexing on each iteration.
            event.errors[0].stacktrace.remove(at: 0)
        }
    } else {
        NSLog("[Bugsnag] Depth parameter was out of range, stacktrace was not trimmed.")
    }
    return event.errors[0].stacktrace
}

Then, add a callback:

let config = BugsnagConfiguration.loadConfig()
config.addOnSendError { (event) -> Bool in
    event.errors[0].stacktrace = self.bugsnagStacktraceDepth(event: event, depth: 1);
    return true
}
Bugsnag.start(with: config)

Using Objective-C, create a function as follows:

NSMutableArray<BugsnagStackframe *> * bugsnagStacktraceDepth(BugsnagEvent *event, int depth) {
    NSMutableArray<BugsnagStackframe *> *newStacktrace = event.errors[0].stacktrace.mutableCopy;
    if (depth > 0 && depth <= newStacktrace.count) { /// Check the depth is in a usable range
        for (int index = 0; index < depth; index++) {
            /// always trim from the top of the stacktrace (index 0),
            /// `newStacktrace` is re-indexing on each iteration.
            [newStacktrace removeObjectAtIndex:0];
        }
    } else {
        NSLog(@"[Bugsnag] Depth parameter was out of range, stacktrace was not trimmed.");
    }
    return newStacktrace;
}

Then, add a callback:

BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnSendErrorBlock:^BOOL (BugsnagEvent *event) {
    event.errors[0].stacktrace = bugsnagStacktraceDepth(event, 1);
    return YES;
}];
[Bugsnag startWithConfiguration:config];

Sessions

Additions

The following options have been added to the BugsnagSession class:

Property/Method	Usage
`app`	A subset of the `app` data contained in error events. (See docs: iOS \| macOS \| tvOS.)
`device`	A subset of the `device` data contained in error events. (See docs: iOS \| macOS \| tvOS.)
`setUser:withEmail:andName` / `setUser(_:email:name)`	The user of the app. (See docs: iOS \| macOS \| tvOS.)

Changes

The following changes have been made to the BugsnagSession class:

v5.x API	v6.x API
`sessionId`	`id`

Deprecations

The following properties/methods have been removed from the BugsnagSession class:

v5.x API	v6.x API
`toJson`	Deprecated - no longer public API.
`toDictionary`	Deprecated - no longer public API.
`stop`	Deprecated in favour of `pauseSession` on the `Bugsnag` client. (See docs: iOS \| macOS \| tvOS.)
`resume`	Deprecated in favour of `resumeSession` on the `Bugsnag` client. (See docs: iOS \| macOS \| tvOS.)
`autoCaptured`	Deprecated - no longer public API.
`handledCount`	Deprecated - no longer public API.
`unhandledCount`	Deprecated - no longer public API.
`stopped`	Deprecated - no longer public API.

User Information

Changes

The following changes have been made to the BugsnagUser class:

v5.x API	v6.x API
`userId`	`id`
`emailAddress`	`email`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UPGRADING.md

UPGRADING.md

Upgrading Guide

Upgrade from 5.X to 6.X

Key points

Bugsnag Client

Starting Bugsnag

Additions

Changes

Deprecations

Configuration

Additions

Changes

Deprecations

Metadata

Breadcrumbs

Additions

Changes

Deprecations

Events (`BugsnagCrashReport`)

Additions

Changes

Deprecations

Depth Replacement

Sessions

Additions

Changes

Deprecations

User Information

Changes

Files

UPGRADING.md

Latest commit

History

UPGRADING.md

File metadata and controls

Upgrading Guide

Upgrade from 5.X to 6.X

Key points

Bugsnag Client

Starting Bugsnag

Additions

Changes

Deprecations

Configuration

Additions

Changes

Deprecations

Metadata

Breadcrumbs

Additions

Changes

Deprecations

Events (BugsnagCrashReport)

Additions

Changes

Deprecations

Depth Replacement

Sessions

Additions

Changes

Deprecations

User Information

Changes

Events (`BugsnagCrashReport`)