Skip to main content

Setting Up Backtrace for iOS

Add Backtrace to your iOS project to automatically detect and report handled and unhandled exceptions, errors, and crashes that occur in your apps written in Swift or Objective-C.

After you've completed the steps on this page, the Backtrace client will be installed and setup with the default configuration settings. Crash and error reports will include the following metadata:

  • system
  • machine
  • signal
  • exception
  • thread
  • process

Supported Platforms​

  • iOS 11+
  • macOS 10.13+
  • tvOS 11+

Privacy manifest​

The iOS SDK contains a privacy manifest to declare the types of data accessed on the device. Please refer to this source document for the specific types of data collected by the SDK.

What You'll Need​

  • A Backtrace account (log in or sign up for a free trial license).
  • Your subdomain name (used to connect to your Backtrace instance). For example, https://example-subdomain.sp.backtrace.io.
  • A Backtrace project and a submission token.

System Requirements​

  • Xcode 10 or above

Install the SDK​

You can install the SDK with Swift Package Manager (SPM) or CocoaPods. The SPM package can be integrated directly in Xcode or by editing your package's Package.swift file.

  1. In Xcode select File > Add Packages, then search for and add https://github.com/backtrace-labs/backtrace-cocoa.git.
  2. Verify your project Package Dependencies list for backtrace-cocoa.
  3. Add Backtrace to your target’s Frameworks, Libraries, and Embedded Content.

Initialize the Backtrace Client​

To initialize BacktraceClient, create a BacktraceCredentials object with the name of your subdomain and submission token, and supply it as a parameter in the BacktraceCredentials constructor:

// provide the name of the subdomain for your Backtrace instance and a submission token
let backtraceCredentials = BacktraceCredentials(submissionUrl: URL(string: "https://submit.backtrace.io/{subdomain-name}/{submission-token}/plcrash")!)

Upload Debug Symbols​

After compiling your application with the new backtrace-cocoa library, make sure symbol files are generated in dSYM format and are uploaded to Backtrace to symbolicate incoming crashes.

For information on how to upload debug symbols, see Symbol Formats and Upload Methods.

Set Debug Symbol Format​

When building your iOS game in Xcode, make sure to configure the build settings to generate dSYM files for any build that you want to debug with Backtrace. By default, Xcode may only generate DWARF files.

To generate debug symbols in dSYM format:

  1. In Xcode, go to your project target's Build Settings.
  2. Under Build Options, set Debug Information Format to DWARF with dSYM File.

Find Debug Symbols​

To find dSYM files while building the project:

  1. In Xcode, build your project.
  2. From the Products folder, select your iOS app.
  3. Right-click, then click Show in Finder.
  4. Zip all the dSYM files and upload to Backtrace.

To find dSYM files while archiving the project:

  1. In Xcode, archive your project.
  2. To open the Archives organizer, go to Window > Organizer and click Archives.
  3. Select your iOS app, then click Show in Finder. dSYMs are stored in a .xcarchive file.
  4. Right-click, then click Show Package Contents.
  5. Search for the dSYMs folder.
  6. Zip all the dSYM files and upload to Backtrace.

Verify the Setup​

At this point, you've installed and setup the Backtrace client to automatically capture exceptions, errors, and crashes in your iOS app.

To test the integration, throw an error an exception to send a report to your Backtrace instance.

Send an Error/NSError​

@objc func send(completion: ((BacktraceResult) -> Void))

Send an NSException​

@objc func send(exception: NSException, completion: ((BacktraceResult) -> Void))

Send macOS Exceptions​

If you want to catch additional exceptions on macOS which are not forwarded by macOS runtime, set NSPrincipalClass to Backtrace.BacktraceCrashExceptionApplication in your Info.plist file.

Alternatively, you can set:

UserDefaults.standard.register(defaults: ["NSApplicationCrashOnExceptions": true])
caution

Make sure to use @try ... @catch or your app will crash.