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.

###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 => "https://github.com/bugsnag/bugsnag-cocoa.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 Bugsnag.zip 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
    Process.setsid
    STDIN.reopen("/dev/null")
    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"])} https://upload.bugsnag.com/")
    end
  end

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

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.

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 bugsnag.com 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"];

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

###user

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:@"[email protected]"];

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

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

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

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

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

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

[Bugsnag configuration].autoNotify = NO;

###notifyURL

By default Bugsnag sends reports to https://notify.bugsnag.com/ 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:@"https://bugsnag.example.com/"];
config.apiKey = @"YOUR_API_KEY_HERE";
[Bugsnag startBugsnagWithConfiguration: config];

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

https://github.com/bugsnag/bugsnag-cocoa/issues

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

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