Aardvark is a library that makes it dead simple to create actionable bug reports.
Objective-C Swift Ruby
Latest commit 492fcb6 Jan 12, 2017 @shawnwelch shawnwelch committed on GitHub Merge pull request #41 from square/shawnwelch/add-watch-3.0
Add support for Apple Watch in CoreAardvark

README.md

Aardvark

CI Status Carthage Compatibility Version License Platform

Aardvark is a library that makes it dead simple to create actionable bug reports.

Getting started

There are only three steps to get Aardvark logging and bug reporting up and running.

1) Install Aardvark.

Using CocoaPods

platform :ios, '8.0'
pod 'Aardvark'

Using Carthage

github "Square/Aardvark"

Using Git Submodules

Or manually checkout the submodule with git submodule add git@github.com:Square/Aardvark.git, drag Aardvark.xcodeproj to your project, and add Aardvark as a build dependency.

2) Setup email bug reporting with a single method call

It is best to do this when you load your application’s UI.

In Swift:

Aardvark.addDefaultBugReportingGestureWithEmailBugReporter(withRecipient:)

In Objective-C:

[Aardvark addDefaultBugReportingGestureWithEmailBugReporterWithRecipient:]

3) Replace calls to print with log.

In Objective-C, replace calls to NSLog with ARKLog.

Reporting Bugs

After doing the above, your users can report a bug by making a two-finger long-press gesture. This gesture triggers a UIAlert asking the user what went wrong. When the user enters this information, an email bug report is generated complete with an attached app screenshot and a text file containing the last 2000 logs. Screenshots are created and stored within Aardvark and do not require camera roll access.

Bug Report Flow

Want to look at logs on device? Push an instance of ARKLogTableViewController onto the screen to view your logs.

Performance

Logs are distributed to loggers on an internal background queue that will never slow down your app. Logs observed by the log store are incrementally appended to disk and not stored in memory.

Customize Aardvark

Want to customize how bug reports are filed? Pass your own object conforming to the ARKBugReporter protocol and the desired subclass of UIGestureRecognizer to [Aardvark addBugReporter:triggeringGestureRecognizerClass:]. You can further customize how bug reports will be triggered by modifying the returned gesture recognizer.

Want to change how logs are formatted? Set your own logFormatter on the ARKEmailBugReporter returned from [Aardvark addDefaultBugReportingGestureWithEmailBugReporterWithRecipient:].

Want to log to the console? [ARKLogDistributor defaultDistributor].defaultLogStore.printsLogsToConsole = YES;.

Want different log files for different features? Create an ARKLogStore for each feature you want to have its own log file and add them to the default log distributor with [[[ARKLogDistributor](Logging/ARKLogDistributor.h) defaultDistributor] addLogObserver:featureLogStore]. Set the logFilterBlock on your ARKLogStore to make sure only the logs you want are observed by the ARKLogStore. Use ARKLogWithType’s userInfo dictionary to specify to which feature a log pertains. See SampleViewController’s tapGestureLogStore for an example.

Want to send your logs to third party services? One log can be easily distributed to multiple services by adding objects conforming to ARKLogObserver to the default ARKLogDistributor via addLogObserver:. SampleCrashlyticsLogObserver is an example of an ARKLogObserver that sends event logs to Crashlytics.

Want to log with Aardvark but don’t want to use Aardvark’s bug reporting tool? Skip step #2 in Getting Started and manually add ARKLogObserver to the default ARKLogDistributor.

Requirements

  • Xcode 8.0 or later
  • iOS 8 or later

Contributing

We’re glad you’re interested in Aardvark, and we’d love to see where you take it. Please read our contributing guidelines prior to submitting a Pull Request.

Thanks, and happy logging!