Advanced Usage

Capturing uncaught exceptions on macOS

By default, MacOS applications do not crash whenever an uncaught exception occurs. To enable this with Sentry:

  • Open the application's Info.plist file
  • Search for Principal class (the entry is expected to be NSApplication)
  • Replace NSApplication with SentryCrashExceptionApplication

Dealing with Scopes

There are three different ways to interact with Scopes in the SDK. Either using configureScope, passing a scope or using the scope callback.


Using SentrySDK:configureScope lets you set context data globally, which will be attached to all future events.

[SentrySDK configureScope:^(SentryScope * _Nonnull scope) {
    [scope setEnvironment:@"debug"];
    [scope setTagValue:@"objc" forKey:@"language"];
    [scope setExtraValue:[NSString stringWithFormat:@"%@", self] forKey:@"currentViewController"];

Passing a Scope Instance

Setting an instance of Scope is helpful when you want to completely control what should be attached to the event. This is helpful in cases where you completely want to control what should be attached to the event.

NSException *exception = [[NSException alloc] initWithName:@"My Custom exception" reason:@"User clicked the button" userInfo:nil];
SentryScope *scope = [[SentryScope alloc] init];
[scope setLevel:kSentryLevelFatal];
// By explicity just passing the scope, only the data in this scope object will be added to the event
// The global scope (calls to configureScope) will be ignored
// Only do this if you have mastered this SDK, otherwise, you risk losing useful info
// If you just want to mutate what's in the scope use the callback, see: captureError
[SentrySDK captureException:exception withScope:scope];

Using Scope Callback

To maintain global state, but mutate context data for one capture call, use the Scope callback:

NSError *error = [[NSError alloc] initWithDomain:@"" code:0 userInfo:@{
    NSLocalizedDescriptionKey: @"Object does not exist"
[SentrySDK captureError:error withScopeBlock:^(SentryScope * _Nonnull scope) {
    // Changes in here will only be captured for this event
    // The scope in this callback is a clone of the current scope
    // It contains all data but mutations only influence the event being sent
    [scope setTagValue:@"value" forKey:@"myTag"];


The SDK enables all integrations by default. To disable any of them:

NSMutableArray *integrations = [SentryOptions defaultIntegrations].mutableCopy;
[integrations removeObject:@"SentryAutoBreadcrumbTrackingIntegration"];
[SentrySDK startWithOptions:@{
    // ...
    @"integrations": integrations
    // ...


This integration is the core part of the SDK. It hooks into all signal and exception handlers to capture uncaught errors or crashes. This integration is also responsible for adding most of the device information to events. If it is disabled, you will not receive crash reports, nor will events contain much device data.


This integration will swizzle some methods to create breadcrumbs e.g.: for UIApplicationDidReceiveMemoryWarningNotification, sendAction:to:from:forEvent: (UI interactions) or viewDidAppear: those breadcrumbs will be attached to your events.

You can edit this page on GitHub.