joshdholtz / bugsnag-cocoa

Bugsnag notifier for iOS and OSX apps

Home Page:

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Bugsnag Notifier for Cocoa

The Bugsnag Notifier for Cocoa gives you instant notification of exceptions thrown from your iOS 4.3+ or OSX applications. The notifier hooks into NSSetUncaughtExceptionHandler, which means any uncaught exceptions will trigger a notification to be sent to your Bugsnag dashboard. Bugsnag will also monitor for fatal signals sent to your application, for example, Segmentation Faults.

Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing exceptions from your applications.

Installation & Setup

###Using CocoaPods (Recommended)

Cocoapods is a library management system for iOS/OSX which allows you to manage your libraries, detail your dependencies and handle updates nicely. It is the recommended way of installing the Bugsnag Cocoa library.

  • Add Bugsnag to your Podfile

    pod 'Bugsnag', :git => ""
  • Install Bugsnag

    pod install
  • Import the Bugsnag.h file into your application delegate.

    #import "Bugsnag.h"
  • In your application:didFinishLaunchingWithOptions: method, initialize Bugsnag by calling,

    [Bugsnag startBugsnagWithApiKey:@"your-api-key-goes-here"];

###Without Cocoapods

  • Download from the latest release

  • Drag Bugsnag.framework from the zip file into your project, enabling "Copy items if needed" when prompted.

  • Under "Build Settings" add "-ObjC" to "Other Linker Flags" (search for "ldflags")

  • Under "General" add "libc++" and "SystemConfiguration.framework" to "Linked Frameworks and Libraries"

  • Add a build phase to upload the symbolication information to Bugsnag

    From the same "Build Phases" screen, click the plus in the bottom right of the screen labelled "Add Build Phase", then select "Add Run Script". Then expand the newly added "Run Script" section, and set the shell to /usr/bin/ruby and copy the following script into the text box,

    fork do
      STDOUT.reopen("/dev/null", "a")
      STDERR.reopen("/dev/null", "a")
      require 'shellwords'
      Dir["#{ENV["DWARF_DSYM_FOLDER_PATH"]}/*/Contents/Resources/DWARF/*"].each do |dsym|
        system("curl -F dsym=@#{Shellwords.escape(dsym)} -F projectRoot=#{Shellwords.escape(ENV["PROJECT_DIR"])}")
  • Import the Bugsnag.h file into your application delegate.

    #import <Bugsnag/Bugsnag.h>
  • In your application:didFinishLaunchingWithOptions: method, register with bugsnag by calling,

    [Bugsnag startBugsnagWithApiKey:@"your-api-key-goes-here"];

Send Non-Fatal Exceptions to Bugsnag

If you would like to send non-fatal exceptions to Bugsnag, you can pass any NSException to the notify method:

[Bugsnag notify:[NSException exceptionWithName:@"ExceptionName" reason:@"Something bad happened" userInfo:nil]];

You can also send additional meta-data with your exception:

[Bugsnag notify:[NSException exceptionWithName:@"ExceptionName" reason:@"Something bad happened" userInfo:nil]
       withData:[NSDictionary dictionaryWithObjectsAndKeys:@"username", @"bob-hoskins", nil]];


You can set the severity of an error in Bugsnag by including the severity option when notifying bugsnag of the error,

[Bugsnag notify:[NSException exceptionWithName:@"ExceptionName" reason:@"Something bad happened" userInfo:nil] withData:nil atSeverity:@"error"];

Valid severities are error, warning and info.

Severity is displayed in the dashboard and can be used to filter the error list. By default all crashes (or unhandled exceptions) are set to error and all [Bugsnag notify] calls default to warning.

Adding Tabs to Bugsnag Error Reports

If you want to add a tab to your Bugsnag error report, you can call the addToTab method:

[Bugsnag addAttribute:@"username" withValue:@"bob-hoskins" toTabWithName:@"user"];
[Bugsnag addAttribute:@"registered-user" withValue:@"yes" toTabWithName:@"user"];

This will add a user tab to any error report sent to that contains the username and whether the user was registered or not.

You can clear a single attribute on a tab by calling:

[Bugsnag addAttribute:@"username" withValue:nil toTabWithName:@"user"];

or you can clear the entire tab:

[Bugsnag clearTabWithName:@"user"];



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. The Notifier will set this to be the top most UIViewController, but if in a certain case you need to override the context, you can do so using this property:

[Bugsnag configuration].context = @"MyUIViewController";


Bugsnag helps you understand how many of your users are affected by each error. In order to do this, we send along a userId with every exception. By default we will generate a unique ID and send this ID along with every exception from an individual device.

If you would like to override this userId, for example to set it to be a username of your currently logged in user, you can set the userId property:

[[Bugsnag configuration] setUser:@"userId" withName:@"User Name" andEmail:@""];

You can also set the email and name of the user and these will be searchable in the dashboard.


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:

[Bugsnag configuration].releaseStage = @"development";


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:

[Bugsnag configuration].notifyReleaseStages = [NSArray arrayWithObjects:@"production", nil];


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

[Bugsnag configuration].autoNotify = NO;


By default Bugsnag sends reports to if you need to change this you can do so by starting Bugsnag with a different configuration object.

BugsnagConfiguration *config = [[BugsnagConfiguration alloc] init];
config.notifyURL = [NSURL URLWithString:@""];
config.apiKey = @"YOUR_API_KEY_HERE";
[Bugsnag startBugsnagWithConfiguration: config];

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:


We love getting issue reports, and pull requests. For more detailed instructions see


The Bugsnag Cocoa notifier is free software released under the MIT License. See LICENSE.txt for details.

ezoic increase your site revenue


Bugsnag notifier for iOS and OSX apps

License:MIT License


Language:C 49.1%Language:Objective-C 46.6%Language:C++ 2.6%Language:Objective-C++ 1.0%Language:Ruby 0.4%Language:Shell 0.3%Language:Swift 0.2%