Rollbar for iOS

Objective-C library for crash reporting and logging with Rollbar.

Install

With Cocoapods

In your Podfile:

pod "Rollbar", "~> 0.1.6"

Make sure to declare your platform as ios at the top of your Podfile. E.g:

platform :ios, '7.0'

Be sure to remember to pod install after changing your Podfile!

Without Cocoapods

Download the Rollbar framework.
Extract the Rollbar directory in the zip file to your Xcode project directory.
In Xcode, select File -> Add Files to "[your project name]" and choose the Rollbar directory from step 2.

Note: if step three doesn't work you can also extract the Rollbar directory anywhere, and drag the .framework files into XCode, allowing XCode to correctly configure the Frameworks.

Setup

In your Application delegate implementation file, add the following import statement:

#import <Rollbar/Rollbar.h>

Then add the following to application:didFinishLaunchingWithOptions::

[Rollbar initWithAccessToken:@"POST_CLIENT_ITEM_ACCESS_TOKEN"];

Replace POST_CLIENT_ITEM_ACCESS_TOKEN with a client scope access token from your project in Rollbar

That's all you need to do to report crashes to Rollbar. To get symbolicated stack traces, follow the instructions in the "Symbolication" section below.

Crash reporting

Crashes will be saved to disk when they occur, then reported to Rollbar the next time the app is launched.

Rollbar uses PLCrashReporter to capture uncaught exceptions and fatal signals. Note that only one crash reporter can be active per app. If you initialize multiple crash reporters (i.e. Rollbar alongside other services), only the last one initialized will be active.

Swift

Importing with Swift requires the additional step of adding the following lines to your Bridging-Header file:

#import <SystemConfiguration/SystemConfiguration.h>
#import <Rollbar/Rollbar.h>

If you have no Bridging Header file, the easiest way to correctly configure it is to add an empty objective-c (dummy.m for instance) file. When you do so, XCode will prompt you to create a bridging header file, and will configure your build environment to automatically include those headers in all your Swift files. After creating the Bridging-Header file, you can delete the objective-c file.

Note: You do not need to import Rollbar if you're using Swift.

The initialization uses Swift syntax:

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    let config: RollbarConfiguration = RollbarConfiguration()
    config.environment = "production"

    Rollbar.initWithAccessToken("YOUR ACCESS TOKEN", configuration: config)

    return true
}

See the these commits for a demo of how to integrate Rollbar into an existing Swift project.

Bitcode

Bitcode is an intermediate representation of a compiled iOS/watchOS program. Apps you upload to iTunes Connect that contain bitcode will be compiled and linked on the App Store. Including bitcode will allow Apple to re-optimize your app binary in the future without the need to submit a new version of your app to the store.

PLCrashReporter does not yet support symbolicating apps built with bitcode. Until a version of PLCrashReporter is available that supports symbolication with bitcode enabled, you'll need to disable bitcode in your project for Rollbar to be able to symbolicate your crash reports.

Logging

You can log arbitrary messages using the log methods:

// Logs at level "info".
// Variants at "debug", "info", "warning", "error", and "critical" all exist.
[Rollbar infoWithMessage:@"Test message"];

// Log a critical, with some additional key-value data
[Rollbar criticalWithMessage:@"Unexcpected data from server" data:@{@"endpoint": endpoint,
                                                                    @"result": result}];

// Or log at a named level
[Rollbar logWithLevel:@"warning" message:@"Simple warning log message"];

Configuration

You can pass an optional RollbarConfiguration object to initWithAccessToken::

RollbarConfiguration *config = [RollbarConfiguration configuration];
config.crashLevel = @"critical";
config.environment = @"production";

[Rollbar initWithAccessToken:@"POST_CLIENT_ITEM_ACCESS_TOKEN" configuration:config];

You can also configure the notifier after initialization by getting the active configuration object and modifying it:

RollbarConfiguration *config = [Rollbar currentConfiguration];
[config setPersonId:@"123" username:@"username" email:@"test@test.com"];

// Will now report with person data
[Rollbar debugWithMessage:@"User hit button A"];

Configuration reference

Properties:

crashLevel: The level that crashes are reported as
Default: error
environment: Environment that Rollbar items will be reported under
Default: unspecified in release mode, development in debug mode.
endpoint: URL items are posted to.
Default: https://api.rollbar.com/api/1/items/

Methods:

`- setPersonId:username:email:`: Sets person data. Each value can either be a `NSString` or `nil`

Symbolication using .dSYM files

To automatically send .dSYM files to Rollbar whenever your app is built in release mode, add a new build phase to your target in Xcode:

Click on your project and then select "Build Phases"
In the top menu bar, click "Editor" and then "Add Build Phase", then "Add Run Script Build Phase"
Change the "Shell" to /usr/bin/python
Paste the following script into the box, using "Paste and Preserve Formatting" (Edit -> Paste and Preserve Formatting):

import os
import subprocess
import zipfile

if os.environ['DEBUG_INFORMATION_FORMAT'] != 'dwarf-with-dsym' or os.environ['EFFECTIVE_PLATFORM_NAME'] == '-iphonesimulator':
    exit(0)

ACCESS_TOKEN = 'POST_SERVER_ITEM_ACCESS_TOKEN'

dsym_file_path = os.path.join(os.environ['DWARF_DSYM_FOLDER_PATH'], os.environ['DWARF_DSYM_FILE_NAME'])
zip_location = '%s.zip' % (dsym_file_path)

os.chdir(os.environ['DWARF_DSYM_FOLDER_PATH'])
with zipfile.ZipFile(zip_location, 'w', zipfile.ZIP_DEFLATED) as zipf:
    for root, dirs, files in os.walk(os.environ['DWARF_DSYM_FILE_NAME']):
        zipf.write(root)

        for f in files:
            zipf.write(os.path.join(root, f))

# You may need to change the following path to match your application settings and Xcode version
info_file_path = os.path.join(os.environ['INSTALL_DIR'], os.environ['INFOPLIST_PATH'])

p = subprocess.Popen('/usr/libexec/PlistBuddy -c "Print :CFBundleVersion" -c "Print :CFBundleIdentifier" "%s"' % info_file_path,
                     stdout=subprocess.PIPE, shell=True)

stdout, stderr = p.communicate()
version, identifier = stdout.split()

p = subprocess.Popen('curl -X POST "https://api.rollbar.com/api/1/dsym" -F access_token=%s -F version=%s -F bundle_identifier="%s" -F dsym=@"%s"' 
                     % (ACCESS_TOKEN, version, identifier, zip_location), shell=True)
p.communicate()

Note: make sure you replace POST_SERVER_ITEM_ACCESS_TOKEN with a server scope access token from your project in Rollbar.

Note: This script will read your application version and idenfier information from the plist file found at info_file_path. Depending on your project settings and the version of Xcode you're using, this file may be in any of the following locations:

$INSTALL_DIR/$INFOPLIST_PATH
$BUILT_PRODUCTS_DIR/$INFOPLIST_PATH
$SOURCE_ROUTE/$INFOPLIST_PATH
$TARGET_BUILD_DIR/$INFOPLIST_PATH
$CONFIGURATION_BUILD_DIR/$INFOPLIST_PATH
$INFOPLIST_FILE
$PRODUCT_SETTINGS_PATH

Developing and building the library

You can include the Rollbar project as a sub-project in your app, or link the Rollbar source files directly into your app. To develop the library by linking the source files directly in your app:

Fork this repo
git clone your fork
In Xcode, remove the Rollbar files from your project if they are currently there
In Xcode, add the Rollbar/ files:
1. Right-click your project
2. Click "Add Files to "
3. Navigate to your rollbar-ios clone and select the Rollbar folder
4. Click "Add"
In Xcode, add the PLCrashReporter framework:
1. Click your project
2. Click the General settings tab
3. Under "Linked Frameworks and Libraries", click the +
4. Click "Add Other..."
5. Navigate to your rollbar-ios clone, then Vendor/
6. Select CrashReporter.framework and click "Open"

You should now be able to build your app with your local clone of rollbar-ios.

To build the Rollbar framework distribution files, open the Rollbar project and make sure the Distribution scheme is active by selecting Editor -> Scheme -> Distribution. Building the project with this scheme selected will create a Dist/ directory containing the Rollbar framework with the proper fat binary.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Help / Support

If you run into any problems, please email us at support@rollbar.com or file a bug report.

mpurland / rollbar-ios