Migration Guide

Migrating from 5.x to 6.x

In this version there are a few breaking changes. This guide should help you to update your code.

Configuration Changes

With this version we changed a few things for the configuration:

• Auto Session Tracking is enabled per default. This feature is collecting and sending health data about the usage of your application.

• Attach stacktraces is enabled per default.

• We bumped the minimum iOS version to 9.0.

• Use a BOOL in SentryOptions instead of NSNumber to store booleans.

• We removed the enabled option from SentryOptions, but we brought it back in 6.0.7 with a slightly changed functionality. Previously setting an empty or incorrect DSN also set enabled to false. This side effect is removed now. Setting the DSN has no impact on enabled. If the DSN is nil or empty or enabled is set to false, the client won't send any data to Sentry.

Breaking Changes

Store Endpoint

This version uses the envelope endpoint. If you are using an on-premise installation it requires Sentry version >= v20.6.0 to work. If you are using sentry.io nothing will change and no action is needed. For this change, we also cache events now in envelopes on the disk. We decided not to take the effort to migrate these few cached events from 5.x to 6.x into envelopes. Instead we remove them from the disk. This means you might lose a few cached events of your users when upgrading.

SDK Inits

We removed the deprecated SDK inits. The recommended way to initialize Sentry is now:

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    // ...
}

Cleanup Public Headers

We cleaned up our public headers and made most of our classes private. If you can't access one of the classes you need please open an issue and tell us your use case so we either make the class public again or provide another API for you.

New type SentryId for eventId

In 5.x we use a nullable NSString to represent an event ID. The SDK, Hub and Client returned this nullable NSString for the event ID for capturing messages, events, errors, etc. With 6.x we have a new type SentryId which is not nullable to represent an event ID. Instead of returning nil when an event couldn't be queued for submission we return SentryId.empty.

5.x

import Sentry

let eventId = SentrySDK.capture(message: "A message")
if (nil != eventId) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}

6.x

import Sentry

let eventId = SentrySDK.capture(message: "A message")
if (eventId != SentryId.empty) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}

New type SentryMessage for Event.message

In 6.x we introduce a new type SentryMessage for event.message. SentryMessage gives you the possibilty to pass a format string with parameters to Sentry, which can help to group similar messages into the same issue.

5.x

import Sentry

let event = Event()
event.message = "Hello World"

6.x

import Sentry

let event = Event()
event.message = SentryMessage(formatted: "Hello World")

Make Scope nonnull for capture methods

In 5.x you could pass a nullable scope to capture methods of the SDK, Hub and Client, such as SentrySdk.captureMessage(). In 6.x we changed the Scope to nonnull and provide overloads for the Hub and the Client.

Please checkout the Changelog for a complete list of changes.

Upgrading from 4.x to 5.x

Here are some examples of how the new SDK works.

Initialization

4.x

do {
    Client.shared = try Client(dsn: "https://examplePublicKey@o0.ingest.sentry.io/0")
    try Client.shared?.startCrashHandler()
} catch let error {
    print("\(error)")
}

5.x

SentrySDK.start(options: [
    "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0",
    "debug": true
])

Add Breadcrumb

4.x

Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test"))

5.x

SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test"))

CaptureMessage with tags/environment/extra

4.x

let event = Event(level: .debug)
event.message = "Test Message"
event.environment = "staging"
event.extra = ["ios": true]
Client.shared?.send(event: event)

5.x

SentrySDK.capture(message: "Test Message") { (scope) in
    scope.setEnvironment("staging")
    scope.setExtras(["ios": true])
    let u = Sentry.User(userId: "1")
    u.email = "tony@example.com"
    scope.setUser(u)
}

setUser

4.x

let u = User(userId: "1")
u.email = "tony@example.com"
Client.shared?.user = user

5.x

let u = Sentry.User(userId: "1")
u.email = "tony@example.com"
SentrySDK.setUser(u)