Skip to content

Latest commit

 

History

History
302 lines (223 loc) · 7.08 KB

README.md

File metadata and controls

302 lines (223 loc) · 7.08 KB
Raw

Honeybadger for iOS and macOS

An SDK for integrating Honeybadger into your iOS and macOS apps. This SDK can be used in both Swift and Objective-C projects.

Installation

SwiftPM compatible CocoaPods compatible

CocoaPods

To install via CocoaPods, create/open your Pods file and add a pod entry for 'Honeybadger'. Make sure use_frameworks! is specified.

use_frameworks!

target 'MyApp' do
	pod 'Honeybadger'
end

Swift Package Manager

Open your app in Xcode, then go to File > Swift Packages > Add Package Dependency, and specify the Honeybadger Cocoa GitHub repo: https://github.com/honeybadger-io/honeybadger-cocoa

Initialization

You will need your Honeybadger API key to initialize the Honeybadger library. You can log into your Honeybadger account to obtain your API key.

In your App Delegate, import the Honeybadger library:

Swift

import Honeybadger

Objective-C

@import Honeybadger;

In your didFinishLaunchingWithOptions method, add the following code to initialize Honeybadger:

Swift

Honeybadger.configure(apiKey:"{{PROJECT_API_KEY}}")

Objective-C

[Honeybadger configureWithAPIKey:@"{{PROJECT_API_KEY}}"];

You can also configure Honeybadger to use an optional custom environment parameter.

Swift

Honeybadger.configure(
	apiKey:"{{PROJECT_API_KEY}}",
	environment:"Staging"
)

Objective-C

[Honeybadger 
	configureWithAPIKey:@"{{PROJECT_API_KEY}}"
	environment:@"Staging"
];

Usage Examples

Errors and exceptions will be automatically handled by the Honeybadger library, but you can also use the following API to customize error handling in your application.

notify

You can use the notify methods to manually send an error as a string or Error/NSError object. If available, the Honeybadger library will attempt to extract a stack trace and any relevant information that might be useful. You can provide an optional context, to include any relevant information about the error. You can also provide a custom class name for the notification, via the optional errorClass parameter, and a custom fingerprint for error grouping, via the optional fingerprint parameter.

Swift

Honeybadger.notify(
	errorString: "My error"
);

Honeybadger.notify(
	errorString: "My error"
	errorClass: "MyCustomErrorType"
);

Honeybadger.notify(
	errorString: "My error", 
	context: ["user_id" : "123abc"]
);

Honeybadger.notify(
	errorString: "My error", 
	fingerprint: "my-custom-error-fingerprint"
);

Honeybadger.notify(
	errorString: "My error", 
	errorClass: "MyCustomErrorType"
	context: ["user_id" : "123abc"]
);

Honeybadger.notify(
	errorString: "My error", 
	errorClass: "MyCustomErrorType"
	fingerprint: "my-custom-error-fingerprint"
);

Honeybadger.notify(
	errorString: "My error", 
	context: ["user_id" : "123abc"]
	fingerprint: "my-custom-error-fingerprint"
);

Honeybadger.notify(
	errorString: "My error", 
	errorClass: "MyCustomErrorType"
	context: ["user_id" : "123abc"]
	fingerprint: "my-custom-error-fingerprint"
);

// ---

Honeybadger.notify(
	error: MyError("This is my custom error.")
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	errorClass: "MyCustomErrorType"
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	context: ["user_id" : "123abc"]
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	fingerprint: "my-custom-error-fingerprint"
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	errorClass: "MyCustomErrorType"
	context: ["user_id" : "123abc"]
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	errorClass: "MyCustomErrorType"
	fingerprint: "my-custom-error-fingerprint"
);

Honeybadger.notify(
	error: MyError("This is my custom error.")
	errorClass: "MyCustomErrorType"
	context: ["user_id" : "123abc"]
	fingerprint: "my-custom-error-fingerprint"
);

Objective-C

[Honeybadger 
	notifyWithString:@"My error"
];

[Honeybadger 
	notifyWithString:@"My error" 
	errorClass:@"MyCustomErrorType"
];

[Honeybadger 
	notifyWithString:@"My error" 
	context:@{ @"user_id" : @"123abc" }
];

[Honeybadger 
	notifyWithString:@"My error" 
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger 
	notifyWithString:@"My error" 
	errorClass:@"MyCustomErrorType"
	context:@{ @"user_id" : @"123abc" }
];

[Honeybadger 
	notifyWithString:@"My error" 
	errorClass:@"MyCustomErrorType"
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger 
	notifyWithString:@"My error" 
	context:@{ @"user_id" : @"123abc" }
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger 
	notifyWithString:@"My error" 
	errorClass:@"MyCustomErrorType"
	context:@{ @"user_id" : @"123abc" }
	fingerprint:@"my-custom-error-fingerprint"
];

// ---

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	errorClass:@"MyCustomErrorType"
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	context:@{ @"user_id" : @"123abc" }
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	errorClass:@"MyCustomErrorType"
	context:@{ @"user_id" : @"123abc" }
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	errorClass:@"MyCustomErrorType"
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	context:@{ @"user_id" : @"123abc" }
	fingerprint:@"my-custom-error-fingerprint"
];

[Honeybadger notifyWithError:
	[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
	errorClass:@"MyCustomErrorType"
	context:@{ @"user_id" : @"123abc" }
	fingerprint:@"my-custom-error-fingerprint"
];

setContext

If you have data that you would like to include whenever an error or an exception occurs, you can provide that data using the setContext method. You can call setContext as many times as needed. New context data will be merged with any previously-set context data.

Swift

Honeybadger.setContext(context: ["user_id" : "123abc"]);

Objective-C

[Honeybadger setContext:@{@"user_id" : @"123abc"}];

resetContext

If you've used setContext to store data, you can use resetContext to clear that data.

Swift

Honeybadger.resetContext();

Objective-C

[Honeybadger setContext];

License

The Honeybadger iOS/macOS SDK is MIT-licensed. See the LICENSE file in this repository for details.