Add BugSnag to your iOS & iPadOS projects for automatic iOS crash reporting — automatically capture and report crashes in released applications.
This documentation is for version 5 of the BugSnag iOS notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.
Add the Bugsnag pod to your Podfile:
pod 'Bugsnag'
Don’t forget to run pod install after updating your Podfile.
Add Bugsnag to your Cartfile:
github "bugsnag/bugsnag-cocoa"
Then run carthage update --platform ios
to generate the frameworks to add to your project from Carthage/Build.
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
Open Xcode and add Bugsnag.xcodeproj to your workspace from the folder with your platform name (iOS, OSX, or tvOS).
Select your project, select your app target, and add libc++.tbd, and libz.tbd to the “Link binary with libraries” section.
Add Bugsnag.framework to the “Embedded Binaries” section (which should automatically add the same entries to “Linked Frameworks and Libraries”).
Add SystemConfiguration.framework to your app target under the “Linked Frameworks and Libraries” section.
Import the BugSnag header in your application delegate’s implementation file:
#import <Bugsnag/Bugsnag.h>
import Bugsnag
In your application:didFinishLaunchingWithOptions: method, initialize Bugsnag:
[Bugsnag startBugsnagWithApiKey:@"your-api-key-goes-here"];
Bugsnag.start(withApiKey: "your-api-key-goes-here")
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.
Within application extensions, initialize BugSnag within the extension view controller initializers:
- (instancetype)initWithCoder:(NSCoder *)coder {
if ((self = [super initWithCoder:coder])) {
[Bugsnag startBugsnagWithApiKey:@"your-api-key-goes-here"];
}
return self;
}
- (instancetype)initWithNibName:(NSString *)nibNameOrNil
bundle:(NSBundle *)nibBundleOrNil {
if ((self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil])) {
[Bugsnag startBugsnagWithApiKey:@"your-api-key-goes-here"];
}
return self;
}
required init?(coder aDecoder: NSCoder) {
super.init(coder: aDecoder)
Bugsnag.start(withApiKey: "your-api-key-goes-here")
}
required override init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: Bundle?) {
super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil)
Bugsnag.start(withApiKey: "your-api-key-goes-here")
}
If you’d like to configure BugSnag further, check out the configuration options reference.
After completing installation and basic configuration, unhandled exceptions, assertion failures (in non-release builds), signal terminations, and out of memory terminations (OOMs) will be reported and automatically appear on your BugSnag dashboard.
Note: Unhandled app terminations will not be detected when a debugger is attached.
If you would like to send handled exceptions to BugSnag, you can pass any NSException object to BugSnag’s notify method:
@try {
// Some potentially crashy code
} @catch (NSException* exception) {
[Bugsnag notify:exception];
}
let exception = NSException(name:NSExceptionName(rawValue: "NamedException"),
reason:"Something happened",
userInfo:nil)
Bugsnag.notify(exception)
Instances of NSError can be sent using the notifyError method:
[Bugsnag notifyError:[NSError errorWithDomain:@"com.example" code:408 userInfo:nil]];
Bugsnag.notifyError(NSError(domain:"com.example", code:408, userInfo:nil))
It can often be helpful to adjust the severity or attach custom diagnostics to handled exceptions. For more information, see reporting handled errors.
BugSnag will automatically capture and attach the following diagnostic data to every exception report:
It can often be helpful to attach application-specific diagnostic data to exception reports. This can be accomplished as follows:
@try {
// Some potentially crashy code
} @catch (NSException* exception) {
[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
[report addMetadata:@{@"company": @"Acme Co."}
toTabWithName:@"account"];
}];
}
let exception = NSException(name:NSExceptionName(rawValue: "NamedException"),
reason:"Something happened",
userInfo:nil)
Bugsnag.notify(exception, block: { report in
report.addMetadata(["company":"Acme Co."], toTabWithName: "account")
})
It is also possible to inspect and modify exception reports before they are delivered using beforeSendBlocks. See the
beforeSendBlocks reference for more details.
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.
This can be accomplished as follows:
[[Bugsnag configuration] setUser:@"userId"
withName:@"User Name"
andEmail:@"user@email.com"];
Bugsnag.configuration()?.setUser("userId", withName:"User Name",
andEmail:"user@example.com")
For more information, see configuration options.
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 shouldAutoCaptureSessions configuration option.
BugSnag will automatically report a session each time the application enters the foreground state.
If you want control over what is deemed a session, you can switch off automatic session tracking with the shouldAutoCaptureSessions option, and manage the session lifecycle using startSession, stopSession and resumeSession.
If you wish to disable error reporting, you can return false within a config block. This would allow for users to opt out of sending error reports, for example:
[Bugsnag.configuration addBeforeSendBlock:^bool (NSDictionary *_Nonnull rawEventData,
BugsnagCrashReport *report) {
return NO; // no error report will be sent
}];
Bugsnag.configuration()?.add(beforeSend: { (rawData, report) -> Bool in
return false // no error report will be sent
}
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. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.
By default, BugSnag captures common events including:
Leaving breadcrumbs can be accomplished as follows:
[Bugsnag leaveBreadcrumbWithMessage:@"Button tapped"];
Bugsnag.leaveBreadcrumb(withMessage: "Button tapped")
When logging breadcrumbs, we’ll keep track of the timestamp, and show both the message and timestamp on your dashboard.
For more information or to customize the diagnostics sent with a breadcrumb, see Customizing individual breadcrumbs.
bugsnag-cocoa, the library
powering BugSnag for macOS, on GitHub