Configuring Backtrace for iOS

Configure Backtrace for your iOS project. This page defines the configuration settings, classes, and methods available with the Backtrace Cocoa SDK.

Usage

Swift

Usage Example

loading...

See full example on GitHub

Objective-C

Usage Example

loading...

See full example on GitHub

Advanced Usage

For more advanced usage of BacktraceClient, you can supply BacktraceClientConfiguration as a parameter. See the following example:

Swift

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let configuration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                 dbSettings: BacktraceDatabaseSettings(),
                                                 reportsPerMin: 10,
                                                 allowsAttachingDebugger: false,
                                                 detectOOM: true)
BacktraceClient.shared = try? BacktraceClient(configuration: configuration)

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                               reportsPerMin: 3
                                               allowsAttachingDebugger: NO
                                               detectOOM: TRUE];

BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];

BacktraceClientConfiguration

Parameters

Setting	Description	Type	Default
credentials (Swift) or initWithCredentials (Objective-C)	The BacktraceCredentials (endpoint URL and submission token) used to initialize the BacktraceClient.	Parameter
dbSettings	The BacktraceDatabaseSettings used to initialize the BacktraceDatabase.	Parameter
reportsPerMin	The maximum number of reports per minute that BacktraceClient will send.	Integer	30
allowsAttachingDebugger	Specifies whether to send reports when the debugger is connected. The options are: false (Swift) / NO (Objective-C): BacktraceClient will send reports when the debugger is connected. true (Swift) / YES (Objective-C): BacktraceClient won't send reports when the debugger is connected.	Boolean	false / NO
detectOOM	Specifies whether to detect and send reports for out of memory (OOM) crashes. The options are: false (Swift) / FALSE (Objective-C): BacktraceClient won't detect or send reports for out of memory (OOM) crashes. true (Swift) / TRUE (Objective-C): BacktraceClient will detect and send reports for out of memory (OOM) crashes.	Boolean	false / FALSE

Database Settings

BacktraceClient allows you to customize the initialization of BacktraceDatabase for local storage of error reports by supplying a BacktraceDatabaseSettings parameter, as follows:

Swift

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let backtraceDatabaseSettings = BacktraceDatabaseSettings()
backtraceDatabaseSettings.maxRecordCount = 1000
backtraceDatabaseSettings.maxDatabaseSize = 10
backtraceDatabaseSettings.retryInterval = 5
backtraceDatabaseSettings.retryLimit = 3
backtraceDatabaseSettings.retryBehaviour = RetryBehaviour.interval
backtraceDatabaseSettings.retryOrder = RetryOder.queue
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                          dbSettings: backtraceDatabaseSettings,
                                                          reportsPerMin: 10)
BacktraceClient.shared = try? BacktraceClient(configuration: backtraceConfiguration)

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceDatabaseSettings *backtraceDatabaseSettings = [[BacktraceDatabaseSettings alloc] init];
backtraceDatabaseSettings.maxRecordCount = 1000;
backtraceDatabaseSettings.maxDatabaseSize = 10;
backtraceDatabaseSettings.retryInterval = 5;
backtraceDatabaseSettings.retryLimit = 3;
backtraceDatabaseSettings.retryBehaviour = RetryBehaviourInterval;
backtraceDatabaseSettings.retryOrder = RetryOderStack;

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: backtraceDatabaseSettings
                                               reportsPerMin: 3
                                               allowsAttachingDebugger: NO];

BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];

BacktraceDatabaseSettings

Parameters

Setting	Description	Type	Default
maxRecordCount	The maximum number of records stored in the database. If set to '0', then there is no record limit.	Integer	0
maxDatabaseSize	The maximum size of the database in MB. If set to '0', then there is no size limit.	Integer	0
retryInterval	The amount of time (in seconds) to wait before the next retry if unable to send a report.	Integer	5
retryLimit	The maximum number of retries to attempt if unable to send a report.	Integer	3
retryBehaviour	The retry behaviour if unable to send a report. The options are: interval: If unable to send a report, the database will retry based on the retryInterval. none: If unable to send a report, the database will not retry.	Enum	interval
retryOrder	The retry order if unable to send a report. The options are: queue: The oldest reports are sent first (FIFO). stack: The newest reports are sent first (LIFO).	Enum	queue

PLCrashReporter

BacktraceClient allows you to customize the configuration of the PLCrashReporter by injecting its instance as follows:

Swift

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials)
BacktraceClient.shared = try? BacktraceClient(
    configuration: backtraceConfiguration,
    crashReporter: BacktraceCrashReporter(config: PLCrashReporterConfig.defaultConfiguration()))
// or
BacktraceClient.shared = try? BacktraceClient(
    configuration: backtraceConfiguration,
    crashReporter: BacktraceCrashReporter(reporter: PLCrashReporter.shared()))

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                                initWithCredentials: credentials];

BacktraceClient.shared = [[BacktraceClient alloc]
                            initWithConfiguration: configuration
                            crashReporter: [[BacktraceCrashReporter alloc] initWithConfig: PLCrashReporterConfig.defaultConfiguration]
                            error: nil];

// or
BacktraceClient.shared = [[BacktraceClient alloc]
                            initWithConfiguration: configuration
                            crashReporter: [[BacktraceCrashReporter alloc] initWithReporter: PLCrashReporter.sharedReporter]
                            error: nil];

Handling Events

BacktraceClient allows you to subscribe to events produced before and after sending each report by attaching an object that follows the BacktraceClientDelegate protocol.

Swift

// assign `self` or any other object as a `BacktraceClientDelegate`
BacktraceClient.shared?.delegate = self

// handle events
func willSend(_ report: BacktraceCrashReport) -> (BacktraceCrashReport)
func willSendRequest(_ request: URLRequest) -> URLRequest
func serverDidFail(_ error: Error)
func serverDidRespond(_ result: BacktraceResult)
func didReachLimit(_ result: BacktraceResult)

Objective-C

// assign `self` or any other object as a `BacktraceClientDelegate`
BacktraceClient.shared.delegate = self;

//handle events
- (BacktraceReport *) willSend: (BacktraceReport *)report;
- (void) serverDidFail: (NSError *)error;
- (void) serverDidRespond: (BacktraceResult *)result;
- (NSURLRequest *) willSendRequest: (NSURLRequest *)request;
- (void) didReachLimit: (BacktraceResult *)result;

For example, you can use BacktraceClientDelegate to modify a report before send:

Swift

func willSend(_ report: BacktraceReport) -> (BacktraceReport) {
    report.attributes["added"] = "just before send"
    return report
}

Objective-C

- (BacktraceReport *)willSend:(BacktraceReport *)report {
    NSMutableDictionary *dict = [report.attributes mutableCopy];
    [dict setObject: @"just before send" forKey: @"added"];
    report.attributes = dict;
    return report;
}

Attributes

You can add custom attributes to send alongside every crash and error report:

Swift

BacktraceClient.shared?.attributes = ["foo": "bar", "testing": true]

Objective-C

BacktraceClient.shared.attributes = @{@"foo": @"bar", @"testing": @YES};

You can also specify a unique set of attributes for a specific report with the willSend(_:) method of BacktraceClientDelegate.

File Attachments

All Reports

You can specify file attachments to send with every crash and error report. File attachments are specified as an array of URL that contain the path to the file.

Swift

guard let libraryDirectoryUrl = try? FileManager.default.url(
     for: .libraryDirectory, in: .userDomainMask, appropriateFor: nil, create: true) else {
     throw CustomError.runtimeError
}

let fileUrl = libraryDirectoryUrl.appendingPathComponent("sample.txt")

var crashAttachments = Attachments()
crashAttachments.append(fileUrl)

BacktraceClient.shared?.attachments = crashAttachments

Objective-C

NSString *fileName = @"myCustomFile.txt";
NSURL *libraryUrl = [[[NSFileManager defaultManager] URLsForDirectory:NSLibraryDirectory
         inDomains:NSUserDomainMask] lastObject];
NSURL *fileUrl = [libraryUrl URLByAppendingPathComponent:fileName];

BacktraceClient.shared.attachments = [NSArray arrayWithObjects:fileUrl, nil];

Per Report

You can specify file attachments to send for a specific report by supplying an array of file paths.

Swift

let filePath = Bundle.main.path(forResource: "test", ofType: "txt")!
BacktraceClient.shared?.send(attachmentPaths: [filePath]) { (result) in
    print(result)
}

Objective-C

NSArray *paths = @[[[NSBundle mainBundle] pathForResource: @"test" ofType: @"txt"]];
[[BacktraceClient shared] sendWithAttachmentPaths:paths completion:^(BacktraceResult * _Nonnull result) {
    NSLog(@"%@", result);
}];

You can also specify a unique set of files for specific reports with the willSend(_:) method of BacktraceClientDelegate.

Error-Free Metrics

Error-free metrics allow you to determine:

• How many of your unique users (i.e., unique device IDs) using your app are experiencing errors/crashes.
• How many application sessions (i.e., individual application sessions from startup till shutdown/exit) of your app are experiencing errors/crashes.

You can track those metrics at-a-glance, as well as in detail to find out what kinds of errors/crashes are most common. For more information, see Stability Metrics Widgets.

Enabling Error-Free Metrics

You can enable error-free metrics as follows:

Swift

Code Sample

loading...

See full example on GitHub

Objective-C

Code Sample

loading...

See full example on GitHub

Breadcrumbs

iOS and macOS Only

Breadcrumbs allow you track events leading up to your crash, error, or other submitted object. When breadcrumbs are enabled, any captured breadcrumbs will automatically be attached as a file to your crash, error, or other submitted object (including native crashes).

Enabling Breadcrumbs

You can enable breadcrumbs as follows:

Swift

Code Sample

loading...

See full example on GitHub

Objective-C

Code Sample

[BacktraceClient.shared enableBreadCrumbs];

Adding Manual Breadcrumbs

You can add breadcrumbs as follows:

Swift

Code Sample

loading...

See full example on GitHub

Objective-C

Code Sample

loading...

See full example on GitHub

caution

We recommend that you do not make calls to addBreadcrumb from performance-critical code paths.

Automatic Breadcrumbs

By default, if you enable breadcrumbs, Backtrace registers handlers to capture common iOS system events, such as low memory warnings, battery state, screen orientation changes, background/foreground/inactive changes, and more.

You can limit the types of automatic events that are captured by specifying which automatic breadcrumb types you want to enable. For example:

Swift

let settings = BacktraceBreadcrumbSettings()
settings.breadcrumbTypes = [BacktraceBreadcrumbType.system, BacktraceBreadcrumbType.configuration]

Objective-C

BacktraceBreadcrumbSettings *settings = [[BacktraceBreadcrumbSettings alloc]
                                             init:4096
                                             maxQueueFileSizeBytes: 64 * 1024
                                             breadcrumbLogFileName:@"bt-breadcrumbs-0"
                                             breadcrumbTypes:@[[NSNumber numberWithInt:BacktraceBreadcrumbTypeManual],
                                                               [NSNumber numberWithInt:BacktraceBreadcrumbTypeLog]]
                                             breadcrumbLevel:BacktraceBreadcrumbLevelInfo];