macOS integration guide

Add BugSnag to your macOS projects to automatically capture and report crashes in released applications.

Installation

Using CocoaPods

Add the Bugsnag pod to your Podfile:

pod 'Bugsnag'

Don’t forget to run pod install after updating your Podfile.

Using Swift Package Manager

Open your Xcode project and select File → Add Packages…

Search for https://github.com/bugsnag/bugsnag-cocoa as the package URL

Set Dependency Rule exact version to v6.30.2, then click Add Package.

Using Carthage

Add Bugsnag to your Cartfile:

github "bugsnag/bugsnag-cocoa"

Then run Carthage to generate the framework to add to your project:

carthage update --use-xcframeworks --platform macos

Drag Bugsnag.framework from Carthage/Build to your project.

Manual installation

Clone the BugSnag GitHub repository:

git clone --branch v6.30.2 https://github.com/bugsnag/bugsnag-cocoa

Drag Bugsnag.xcodeproj into your Xcode workspace.

Select your project in the Project Navigator and in the project editor that appears, select your app’s target.

Under the General tab, click the Frameworks, Libraries and Embedded Content section’s + button and select Bugsnag.framework (from ‘Bugsnag-macOS’).

Basic configuration

Configure your API key by adding a bugsnag Dictionary to your Info.plist file:

Or in XML:

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

App Delegate

If your app implements an app delegate, import the Bugsnag module and initialize Bugsnag in the applicationDidFinishLaunching: method:

#import <Bugsnag/Bugsnag.h>

@implementation AppDelegate

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    [Bugsnag start];
}

import Bugsnag

@NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDidFinishLaunching(_ aNotification: Notification) {
        Bugsnag.start()
    }
}

SwiftUI App Life Cycle

If your app adopts the SwiftUI App Life Cycle and does not implement an app delegate, import the Bugsnag module and initialize BugSnag within the App conformer’s initializer:

import Bugsnag

@main
struct SwiftUIApp: App {
    init() {
        Bugsnag.start()
    }
}

Network request breadcrumbs

If your app makes network requests via URLSession, you can install the BugsnagNetworkRequestPlugin to capture network requests as breadcrumbs in your error reports. For installation instructions, see our Customizing breadcrumbs guide.

Further configuration

If you’d like to configure Bugsnag further, check out the configuration options reference.

Showing full stacktraces

Stacktraces from Apple platforms include backtraces with memory addresses, but symbolication is required to replace the memory addresses with human-readable function names, file paths, and line numbers. Follow the Showing full stacktraces guide to configure symbolication during your build and release process.

Reporting unhandled exceptions

Mac exceptions in the main thread are caught by Cocoa and don’t reach Bugsnag by default.

To report these exceptions, create a new Cocoa class in your Mac project that is a subclass of NSApplication and define a reportException method that sends the exception to Bugsnag:

#import <Bugsnag/Bugsnag.h>

- (void)reportException:(NSException *)theException {
    [Bugsnag notify:theException];
    [super reportException:theException];
}

import Bugsnag

func reportException(exception: NSException) {
    Bugsnag.notify(exception)
    super.reportException(exception)
}

Finally, edit your target settings by clicking on the Info tab and editing “Principal class” to contain your new NSApplication class name. Exceptions on your main thread will now be sent to Bugsnag.

[[NSUserDefaults standardUserDefaults]
    registerDefaults:@{
        @"NSApplicationCrashOnExceptions": @YES }];

UserDefaults.standard.register(defaults:
    ["NSApplicationCrashOnExceptions": true])

It is worth noting that you should also use try{}catch{} blocks inside your application delegate functions and manually notify Bugsnag of any exceptions. This is another limitation of the exception handling in Mac applications that the exception handler is only guaranteed to be called after application initialization has completed.

Reporting app hangs

When the main thread of an app is unresponsive for a period of time it will appear to have frozen and may be terminated by the system watchdog as described in Apple’s documentation.

Detection of these “fatal” app hangs is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option. By default fatal app hangs are reported when the app is terminated after the main thread has been unresponsive for 2000ms.

You can also report non-fatal app hangs (i.e. hangs that did not result in the app being killed) by configuring a minimum app hang threshold duration. This threshold applies to both fatal and non-fatal app hangs and is used by BugSnag to prepare an app hang event report when it is exceeded; if the app subsequently recovers from the hang, a non-fatal hang is reported otherwise a fatal hang will be reported if the app is terminated.

Follow the Reporting app hangs guide to configure this functionality.

Reporting thermal kills

BugSnag detects terminations of your app by the operating system due to the device overheating.

Thermal kill detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option.

Reporting handled exceptions

If you would like to send handled exceptions to Bugsnag, you can pass any NSError object to Bugsnag’s notifyError method:

NSError *error = nil;
BOOL success = [[NSFileManager defaultManager] removeItemAtPath:@"//invalid/file" error:&error];
if (!success) {
    [Bugsnag notifyError:error];
}

do {
    try FileManager.default.removeItem(atPath:"//invalid/file")
} catch {
    Bugsnag.notifyError(error);
}

Instances of NSException can be sent using the notify method:

@try {
    [NSJSONSerialization dataWithJSONObject:badlyFormattedJson options:0 error:nil];
} @catch (NSException* exception) {
    [Bugsnag notify:exception];
}

let exception = NSException(name:NSExceptionName(rawValue: "NamedException"),
                            reason:"Something happened",
                            userInfo:nil)
Bugsnag.notify(exception)

Adding diagnostics or adjusting severity

It can often be helpful to adjust the severity or attach custom diagnostics to handled exceptions. For more information, see Reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

BugSnag will automatically capture and attach the following diagnostic data to every exception report:

• Full stack traces for all threads.
• App state including running time and time in foreground.
• Build information including name, version/build and release stage.
• Device specification including model, OS version and total memory.
• System state including free memory and battery level.

For more information see Automatically captured data.

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to BugSnag:

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)

For more information, see Customizing error reports.

Identifying users

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. BugSnag includes helpers for attaching an identifier, email address and name to reports that will be searchable in the dashboard.

By default we will generate a unique ID and send this ID along with every error report from an individual device. If you would like to override this identifier you can set the user ID property.

[Bugsnag setUser:@"3" withEmail:@"bugs.nag@bugsnag.com" andName:@"Bugs Nag"];

Bugsnag.setUser("3", withEmail: "bugs.nag@bugsnag.com", andName: "Bugs Nag")

For more information, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures common events including:

• Menu presentation
• Table view selection
• Window visibility changes
• Undo and redo
• Thermal state changes
• Non-fatal errors

Network request breadcrumbs

If your app makes network requests via URLSession, you can install the BugsnagNetworkRequestPlugin to capture network requests as breadcrumbs in your error reports. For installation instructions, see our Customizing breadcrumbs guide.

Leaving custom breadcrumbs

You can use the leaveBreadcrumb method to log potentially useful events in your own applications:

[Bugsnag leaveBreadcrumbWithMessage:@"Button tapped"];

Bugsnag.leaveBreadcrumb(withMessage: "Button tapped")

Bugsnag will keep track of the time and order of the breadcrumbs and show them on your dashboard.

Additional data can also be attached to breadcrumbs by providing the optional type and metadata parameters. For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

Session tracking

BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions configuration option.

BugSnag will automatically report a session each time the app is launched or enters the foreground after being in the background for at least 30 seconds.

For more information about controlling session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

[Bugsnag addFeatureFlagWithName:@"Checkout button color" variant:@"Blue"];
[Bugsnag addFeatureFlagWithName:@"New checkout flow"];

Bugsnag.addFeatureFlag(name: "Checkout button color", variant: "Blue")
Bugsnag.addFeatureFlag(name: "New checkout flow")

For more information, see Feature flags & experiments.

Identifying crashes at launch

By default BugSnag will identify crashes that occur whilst your app is launching, allowing you to prioritize fixing high-impact launch crashes.

Additionally you can use BugSnag to detect recurrent launch crashes: allowing you to take evasive action in your app, such as resetting data or turning off application features.

Follow the Identifying crashes at launch guide to configure this functionality.

Next steps

• Explore demo projects
• View bugsnag-cocoa, the library powering BugSnag for macOS, on GitHub
• Get support for your questions and feature requests