Cocoa

This is the documentation for our Cocoa SDK (Swift and Objective-C). If you are migrating from an older version, please consider our Migration Guide. Also always make sure to follow the changelog

Installation

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

It supports iOS (>= 8.0), tvOS (>= 9.0), macOS (>= 10.10) and partially watchOS (>= 2.0).

CocoaPods

We recommend installing the SDK with CocoaPods.. To integrate Sentry into your Xcode project, specify it in your Podfile:

platform :ios, '8.0'
use_frameworks! # This is important

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

Afterwards run pod install.

Carthage

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

github "getsentry/sentry-cocoa" "5.0.0-beta.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

To integrate Sentry into your Xcode project using SPM, open your App in Xcode and open File -> Swift Packages -> Add Package Dependency. Then add the SDK by entering the git repo url https://github.com/getsentry/sentry-cocoa.git, and select a version (or branch) on the next page.

NOTE: Version tags or branches need to have the Package.swift file in it or Xcode won’t be able to install the package.

Configuration

Make sure you initalize the SDK as soon as possible in your application lifecycle e.g. in your AppDelegate application:didFinishLaunchingWithOptions method:

@import Sentry;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [SentrySDK initWithOptions:@{
        @"dsn": @"___PUBLIC_DSN___",
        @"debug": @(YES)
    }];
    return YES;
}
import Sentry // Make sure you import Sentry

// ....

func application(_ application: UIApplication, 
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    _ = SentrySDK(options: [
        "dsn": "___PUBLIC_DSN___",
        "debug": true // Enabled debug when first installing is always helpful
    ])
    return true
}

Debug Symbols

Before capturing crashes, you need to provide debug information to Sentry. Debug information is provided by uploading dSYM files using one of two methods, dependent on your setup:

Testing if the SDK works

To validate that the SDK is correctly set up and connected to your Sentry project, capture a test message:

[SentrySDK captureMessage:@"My first test message"];
SentrySDK.capture(message: "My first test message")

If everything is working correctly, this message should appear within seconds in your Sentry project.

Crash Handling

Our SDK hooks into all signal and exception handlers, except for MacOS. If you are using MacOS, please see the additional step provided in Advanced Usage To try it out, the SDK provides a test crash function:

[SentrySDK crash];
SentrySDK.crash()

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

Crashes are submitted only upon re-launch of the application. To view the crash in Sentry, close your app and re-launch it.

Deep Dive