iOS

Raygun4iOS - iOS Error & Crash Reporting

Raygun crash reporting and error monitoring is available for iOS with the raygun4iOS provider. The raygun4iOS provider can be used in Objective-C and Swift iOS applications. The setup instructions below includes steps to integrate Raygun4iOS in both types of applications. The features described in these docs also apply to both languages.

The latest version of Raygun4iOS supports iOS v7.1.0 and higher. If you still need to support lower iOS versions, you can either include an iOS version check in your code to determine if Raygun4iOS should be enabled, or use Raygun4iOS 1.6.0 (legacy versions are available when following the manual install instructions below).

Setup instructions (Using CocoaPods)

Raygun can be obtained through CocoaPods which is an iOS dependency manager. Read more about CocoaPods here, or see further below for the manual setup instructions.

1. Update Podfile

Add the following to your project's Podfile:

platform :ios
pod 'Raygun4iOS'

2. Run pod install

Open a shell, navigate to the location of your project's Podfile and run:

pod install

From now on, make sure to always open the Xcode workspace instead of the project file when building your project.

3. Import dependency

In AppDelegate.m, import the Raygun.h header:

#import <Raygun4iOS/Raygun.h>

4. Start the Raygun error reporter

In the application function of AppDelegate.m, add the following code to start the Raygun error reporter. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

[Raygun sharedReporterWithApiKey:@"YOUR_APP_API_KEY"];

The steps above will cause all unhandled exceptions to be sent to your Raygun account.

Toubleshooting

If your project does not build after performing these steps, your projects "Other Linker Flags" option is most likely overriding the Pods project option. (You'd get a warning about this after running pod install). To fix this, click your project in Xcode, and then select your main app target. Go to the "Build Settings" tab, search for "Other Linker Flags" and add $(inherited) to this option and you'll be good to go.

Setup instructions (Manual)

If you don't use CocoaPods, follow these instructions to manually download and reference the Raygun4iOS framework.

1. Download Raygun4iOS

Download and unzip the latest version from here: Raygun4iOS Version 2.3.4

Legacy versions can be downloaded from the changelog.

2. Reference Raygun4iOS in your project

In Xcode, click on your project and then select your main app target. Go to the "Build Phases" tab and expand "Link Binary With Libraries". Drag Raygun4iOS.framework into the library list.

3. Import dependency

In AppDelegate.m, import the Raygun.h header:

#import <Raygun4iOS/Raygun.h>

4. Start the Raygun error reporter

In the application function of AppDelegate.m, add the following code to start the Raygun error reporter. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

[Raygun sharedReporterWithApiKey:@"YOUR_APP_API_KEY"];

5. Link the C++ library

In Xcode, click on your project and then select your main app target. Go to the "Build Settings" tab, search for "Other Linker Flags" and add "-lc++" to this setting.

The steps above will cause all unhandled exceptions to be sent to your Raygun account.

Setup instructions (Swift)

Swift is another langauge created by Apple for building iOS (and OSX) applications. The same Raygun4iOS provider mentioned above for Objective-C iOS applications can also be used for error reporting in Swift iOS apps.

  1. Installation - same as with Objective-C applications, there are two ways to install Raygun4iOS into your Swift iOS app: via the CocoaPods dependancy manager, or by manually downloading and referencing the library. The CocoaPods instructions and the download link can be found above.
  2. Once your application is referencing the Raygun4iOS library, import Raygun4iOS into the bridging-header file of your Swift app:
    #import <Raygun4iOS/Raygun4iOS.h>
  3. Finally, in AppDelegate.swift, add the following code to the application function:
    Raygun.sharedReporterWithApiKey("YOUR_APP_API_KEY")

‚ÄčA complete tutorial of these steps can be found here.

Symbolication

The iOS provider transmits encoded crash reports it receives from your app as it runs on devices or emulators. To turn these crash reports into useful data that you can use to debug, Raygun requires your app's dSYM file. This is generated on build in Xcode and is unique to every version of your app's source. When you are finished testing locally and are deploying a new build, you need to upload the new dSYM file corresponding to that build.

Once Raygun has that build's dSYM file, the encoded crash reports will be turned into complete back traces, with line numbers and file names.

Uploading a dSYM file

Here are 3 options for uploading your dSYM files to your Raygun account:

Raygun Sidekick - dSYM uploader Mac OS X app

The Raygun Sidekick is a Mac OS X application that sits in your Mac menu bar which will detect, zip and upload the appropriate dSYM file in just a few clicks. It is highly recommend that you use the Raygun Sidekick rather than tediously uploading the dSYM files yourself as described below.

Download the Raygun Sidekick right here and check out the documentation for more info.

Manual upload

To manually upload dSYM files, visit the Raygun dashboard, click on dSYM Center in the sidebar, then upload the dSYM file by drag 'n dropping or using Finder.

You can do this at any time. If you deploy a new build and Raygun receives crash reports without the dSYM file, it will store them ready for you to upload it. When you do, visit an error from that build and click on 'Reprocess crash report'. After a short delay, the stack trace will appear.

Automated uploading via cURL

For sending dSYMs to Raygun in other processes such as build scripts or the terminal, you can post via cURL:

curl -H "Host: app.raygun.io" -H "Authorization: Basic <token>" --form "DsymFile=@build/${APP_NAME}-${BUILD_NUMBER}-dSYM.zip" https://app.raygun.io/dashboard/${APP_ID}/settings/symbols

<token> should be replaced with a basic auth token which can be created by Base64 encoding your Raygun account credentials in the following format (make sure not to forget the colon between them): username:password

APP_NAME and BUILD_NUMBER make up the name of the zippped dSYM. What you name the zipped dSYM file is totally up to you - app name and build number is an example.

APP_ID is available in the URL of your app in the Raygun dashboard.

Make sure to include the @ before the dSYM file path which tells cURL that the file itself is to be sent, rather than sending the path string. Missing the @ will result in an Invalid dSYM file response.

Unique user tracking

Raygun supports tracking the unique users who encounter bugs in your apps. You can transmit the current user who was affected by the exception by calling the identify method on the current raygun client (code example below). You pass a string to this method to represent the user which could be a database id, username, email address or whatever works for you. A count of affected users will then appear in the error statistics in Raygun. If you provide an email address, you will see it on the error page in Raygun, and if they have an associated Gravatar you will see that too. If the user context changes, for instance on log in/out, you should remember to call identify again to store the updated identity. This feature is optional if you wish it disabled for privacy purposes. Below is an example of setting the user identity after the usual Raygun4iOS initialization.

[Raygun sharedReporterWithApiKey:@"YOUR_APP_API_KEY"];
[[Raygun sharedReporter] identify:@"UNIQUE_USER_IDENTITY"];

Tags

An array of strings can be sent with each exception and displayed in Raygun. This can be used to categorize exceptions or add additional contextual information. These tag values are also searchable in your Raygun dashboard so that you can find all exception instances that you've marked with a particular flag.

Per exception tags

When manually sending an exception to Raygun, you can include an array of tags for that exception as demonstrated below.

[[Raygun sharedReporter] send:exception withTags: array];

Global tags

Sometimes you may want certain tags to be sent with all exceptions regardless of if you manually sent them, or if Raygun4iOS automatically reports them. This can be done by setting the tags property on the shared Raygun reporter as in the example below. Global tags can be changed at any point in your application by setting this tags property.

[[Raygun sharedReporter] setTags(array)];

Custom data

Each exception can be reported with a dictionary of custom data. This data gets displayed in Raygun and can be used to record useful contextual information for debugging. Please note: currently the custom data dictionary should only include simple values such as strings and numbers.

Per exception custom data

While sending an exception, you can also include a dictionary of custom data along with that exception. Below is an example of how to do this. The tags array can be nil if you don't have any tags for this exception.

[[Raygun sharedReporter] send:exception withTags: array withUserCustomData: dictionary];

Global custom data

You can set common custom data on the shared Raygun reporter like in the example below. This custom data will be included with all manually sent and automatically detected exceptions. You can set global custom data any time in your application to change the data that gets sent with subsequently sent exceptions.

[[Raygun sharedReporter] setUserCustomData(dictionary)];

Raygun4iOS Changelog

Raygun4iOS Changelog

Here is a list of all the legacy versions of Raygun4iOS as well as the latest version. Each version listed provides a download link and its changelog.

Latest version

Version 2.3.4 May 26th 2017

  • Fixed minor memory leaks.
  • Mitigate AsyncLocator warnings.
  • Fix additional duplicate symbols issue.

Legacy versions

Version 2.3.3 Dec 1st 2016

  • Resolved issue with setting new user information in Swift.

Version 2.3.2 Nov 30th 2016

  • Resolved issue with setting new user information leading to a crash.

Version 2.3.1 Nov 8th 2016

  • Minor stacktrace improvements.

Version 2.3.0 Nov 8th 2016

  • Expanded automatic network logging coverage.
  • Able to enable/disable network logging when using Pulse.
  • Added the ability to filter out data sent for network requests or view load timings.

Version 2.2.1 Sep 13th 2016

  • Capture additional stacktrace lines.

Version 2.2.0 Feb 10th 2016

  • Resolved duplicate symbols compile time issue when another PLCrashReporter is present in the project.
  • Added global tags feature - just like the global custom data feature.
  • Added option to specify the application version.

Version 2.1.3 Oct 28th 2015

  • Resolved Xcode 7 warnings when doing a release build.
  • Reduced the size of the Raygun4iOS framework.

Version 2.1.2 Oct 8th 2015

  • Enabled bitcode so that apps with bitcode enabled can build.
  • Resolved mismatched version warnings.
  • Resolved broken swift debugger issue.

Version 2.1.1 Sep 18th 2015

  • Resolved an issue preventing exception reports being sent on iOS 7.1.2 devices
  • Added a nil check for the message and reason of exceptions.
  • Updated to plcrash reporter 1.3

Version 2.1.0 Jun 18th 2015

  • Additional user info can be sent using the new identifyWithUserInfo method.
  • Machine name can be omitted from reports using the new init and sharedReporter method overloads.
  • resolved a memory issue with the userCustomData property.
  • Ensure the occurredOn date is in the correct format.

Version 2.0.0 May 7th 2015

  • Recreated the project to use the built-in Xcode static framework project template.
  • Send device model in each error report.
  • Use globally set custom data in all manual send functions including crash.

Version 1.6.0 Feb 11th 2015

  • Create a Raygun reporter that doesn't enable crash reporting - useful if you just want to report handled exceptions: [Raygun sharedReporterWithApiKey:@"YOUR_APP_API_KEY" withCrashReporting:false];
  • setUserCustomData to provide a custom data dictionary that gets sent with all automatic crash reports and manual sends.
  • send method overload to provide a name and reason string - useful when there isn't an NSException or NSError.
  • sendError method to send NSError information.

Version 1.5.0 Nov 14th 2014

  • New send methods to send a list of tags and a dictionary of custom data.
  • Corrected the app version number in the error reports.

Version 1.4.2 Nov 5th 2014

  • Resolved issue if the locale can not be determined.
  • Resolved memory allocation issue in iOS 8+ of the user identifier when manually sending errors.
  • Include the iOS error-signal name and code in the message payload.

Version 1.4.1 Jul 22nd 2014

  • Fixes a bug around client version and user identifier being null when inserted into the dictionary to be serialised.

Version 1.4.0 Jul 16th 2014

  • Pull in fixes from plcrashreporter.
  • Allow manually sending exceptions.

Version 1.3.0 May 30th 2014

  • Support older iOS versions down to 5.1

Version 1.2.1 May 6th 2014

  • Send the application version as part of the payload.
  • Prefix the PL crash report classes so they don't conflict with other users of it.

Version 1.2.0 Jan 27th 2014

  • Allow user identification, similar to the other providers.
  • Store the version of the Raygun4iOS provider that generated the report in the report to carry over when Raygun4iOS is updated.
  • Updated license to comply with PLCrashReporter license.
  • Support pre iOS7 Base64 encoding.

Version 1.1.1 Nov 29th 2013

  • Recreated the framework using the ios universal framework template.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.