macOS integration guide

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

Installation

This documentation is for version 6 of the Bugsnag macOS 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.

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

In your Xcode project: File → Add Packages…

Search for https://github.com/bugsnag/bugsnag-cocoa as the package repository URL, then click Add Package.

Using Carthage

Add Bugsnag to your Cartfile:

github "bugsnag/bugsnag-cocoa"

Then run carthage update --platform macos to generate the frameworks to add to your project from Carthage/Build.

Manual installation

  1. Clone the Bugsnag GitHub repository and its submodules into your source control environment:

    git clone --recursive https://github.com/bugsnag/bugsnag-cocoa
    cd bugsnag-cocoa && git checkout tags/<latest release>
    

    where <latest release> is the most recent release of the library

  2. Open Xcode and drag Bugsnag.xcodeproj to your workspace.

  3. Select your project in the Project Navigator, then add the following libraries to Frameworks, Libraries and Embedded Content section of your app’s target:

    • Bugsnag.framework (select iOS, tvOS or macOS as appropriate)
    • SystemConfiguration.framework
    • libc++.tbd
    • libz.tbd

Basic configuration

Configure your API key by adding a bugsnag Dictionary to 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>

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()
    }
}

Configuring symbolication

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 symbolication guide to configure symbolication during your build and release process.

Further configuration

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

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.

Although AppKit prevents your app from terminating when an exception is thrown on the main thread, it is likely to leave your app in a corrupted state because the Cocoa frameworks are not exception safe.


If an exception is thrown when handling any UI interaction (such as a button click) the app will typically not work correctly from that moment on.


For more predictable behaviour, you can use the following hidden AppKit feature that makes uncaught exceptions crash the app, much like on iOS.


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

Unhandled exceptions are sent to your Bugsnag dashboard when the app next launches. They will not be reported when the debugger is attached.

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 are enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option. 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 threshold hang duration.

Fatal app hangs are sent to your Bugsnag dashboard when the app next launches.

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.

Thermal kill events are sent to your Bugsnag dashboard when the app next launches. They will not be reported when the debugger is attached.

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 crash, 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:

  • Low memory warnings
  • Device rotation
  • Menu presentation
  • Screenshot capture (not the screenshot itself)
  • Undo and redo
  • Table view selection
  • Window visibility 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.

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