Product
API
Sandbox
Sign In

Cocoa

This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version 3.0.0 we’ve switched our internal code from Swift to Objective-C to maximize compatibility. Also we trimmed the public API of our SDK to a minimum. Check out Migration Guide or Advanced Usage for details.

Getting Started

Getting started with Sentry is a three step process:

  1. Sign up for an account
  2. Install your SDK
  3. Configure it

Installation

The SDK can be installed using CocoaPods, Carthage, or Swift Package Manager. This is the recommended client for both Swift and Objective-C.

We recommend installing Sentry with CocoaPods.

CocoaPods

To integrate Sentry into your Xcode project using CocoaPods, specify it in your Podfile:

Copied
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

target 'YourApp' do
  pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '4.5.0'
end

Afterwards run pod install. In case you encounter problems with dependencies and you are on a newer CocoaPods you might have to run pod repo update first.

Carthage

To integrate Sentry into your Xcode project using Carthage, specify it in your Cartfile:

Copied
github "getsentry/sentry-cocoa" "4.5.0"

Run carthage update to download the framework and drag the built Sentry.framework into your Xcode project.

We also provide a pre-built version for every release which can be downloaded at releases on GitHub.

Swift Package Manager

Starting with sentry-cocoa version 4.4.3, we support Swift Package Manager.

To integrate Sentry into your Xcode project using SPM, open your App in Xcode and open File -> Add Packages. Then add sentry-cocoa by entering the git repo url https://github.com/getsentry/sentry-cocoa.git in the top right search field. Define your dependency rule by selecting the SDK version (or branch), and then click the "Add Package" button.

Configuration

To use the client, change your AppDelegate’s application method to instantiate the Sentry client:

Copied
import Sentry

func application(_ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Create a Sentry client and start crash handler
    do {
        Client.shared = try Client(dsn: "https://examplePublicKey@o0.ingest.sentry.io/0")
        try Client.shared?.startCrashHandler()
    } catch let error {
        print("\(error)")
    }

    return true
}

If you prefer to use Objective-C you can do so like this:

Copied
@import Sentry;

NSError *error = nil;
SentryClient *client = [[SentryClient alloc] initWithDsn:@"https://examplePublicKey@o0.ingest.sentry.io/0" didFailWithError:&error];
SentryClient.sharedClient = client;
[SentryClient.sharedClient startCrashHandlerWithError:&error];
if (nil != error) {
    NSLog(@"%@", error);
}

Debug Symbols

Before you can start capturing crashes you will need to tell Sentry about the debug information by uploading dSYM files. Depending on your setup this can be done in different ways:

Testing a Crash

If you would like to test the crash reporting you will need to cause a crash. While the seemingly obvious method would be to make it crash on launch, this will not give the Sentry client a chance to actually submit the crash report. Instead, we recommend triggering a crash from a button tap.

You can use the following methods to cause a crash:

  • Swift:

    Copied
    Client.shared?.crash()

  • Objective-C:

    Copied
    [SentryClient.sharedClient crash];

If you crash with a debugger attached, nothing will happen.

Crashes are only submitted upon re-launching the application. To see the crash in Sentry, close the app and launch it again from the springboard.

Deep Dive

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
Suggest an edit to this page   |  Contribute to Docs   |  Report a problem