Apple TV integration guide

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

Installation

Add the Bugsnag pod to your Podfile:

pod 'Bugsnag'

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

Using Carthage

Add Bugsnag to your Cartfile:

github "bugsnag/bugsnag-cocoa"

Then run carthage build to generate the binaries 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 add Bugsnag.xcodeproj to your workspace from the folder with your platform name (iOS, OSX, or tvOS).

  3. Add KSCrash.xcodeproj to your workspace from Carthage/Checkouts/KSCrash and the folder with your platform name (iOS, OSX, or tvOS).

  4. Select your project, select your app target, and add Bugsnag.framework and KSCrash.framework to the “Link binary with libraries” section.

Basic configuration

Import the Bugsnag header in your application delegate’s implementation file:

#import <Bugsnag/Bugsnag.h>

In your application:didFinishLaunchingWithOptions: method, initialize Bugsnag:

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

Further configuration

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

Configuring symbolication

When you compile a release build of an Cocoa application, debug symbols such as method and class names are automatically stripped from the binary, making stack traces more difficult to interpret.

In order to recombine crashes with debug symbols, Bugsnag needs a copy of the dSYM file generated for each release. See the symbolication guide for more details.

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions, assertion failures, and signal terminations will be reported and automatically appear on your Bugsnag dashboard.

Reporting handled exceptions

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];
}

Instances of NSError can be sent using the notifyError method:

[Bugsnag notifyError:[NSError errorWithDomain:@"com.example" code:408 userInfo:nil]];

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:

  • A full stacktrace
  • Battery state
  • Device model and OS version
  • Thread state for all threads
  • Release stage (production, debug, etc)
  • App running duration in the foreground and/or background
  • A device- and vendor-specific identifier

Attaching custom diagnostics

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.metadata = @{@"company": @"Acme Co."}
    }];
}

It is also possible to inspect and modify exception reports before they are delivered using beforeSendBlocks. See the beforeSendBlocks reference for more details.

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.

This can be accomplished as follows:

[[Bugsnag configuration] setUser:@"userId"
                        withName:@"User Name"
                        andEmail:@"user@email.com"];

For more information, see configuration options.

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. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures common events including:

  • Low memory warnings
  • Device rotation (if applicable)
  • Menu presentation
  • Screenshots
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors

Attaching custom breadcrumbs

Leaving breadcrumbs can be accomplished as follows:

[Bugsnag leaveBreadcrumbWithMessage:@"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.

Next steps

  • View bugsnag-cocoa, the library powering Bugsnag for Apple TV, on GitHub
  • Get support for your questions and feature requests