macOS

Documentation - Raygun4MacOS - macOS Error & Crash Reporting

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

Setup instructions (Using CocoaPods)

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

1. Update Podfile

Add the following under the relevant target(s) within your project's Podfile:

pod 'Raygun4MacOS'

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 <Raygun4MacOS/Raygun.h>

4. Enable the Raygun provider

In the application function of AppDelegate.m, add the following code to enable the Raygun provider. 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_API_KEY_HERE"] attachPulse];

The steps above will cause all unhandled exceptions and real user monitoring analytics to be sent to your Raygun account.

Setup instructions (Manual)

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

1. Download Raygun4MacOS

Download and unzip the current version from here: Raygun4MacOS Version 1.0.2

2. Reference Raygun4MacOS 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 Raygun4MacOS.framework into the library list.

3. Import dependency

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

#import <Raygun4MacOS/Raygun.h>

4. Enable the Raygun provider

In the application function of AppDelegate.m, add the following code to enable the Raygun provider. 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_API_KEY_HERE"] attachPulse];

Setup instructions (Swift)

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

  1. Installation - same as with Objective-C applications, there are two ways to install Raygun4MacOS into your Swift Mac 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 Raygun4MacOS library, import Raygun4MacOS into the bridging-header file of your Swift app:
    #import <Raygun4MacOS/Raygun4MacOS.h>
  3. Finally, in AppDelegate.swift, add the following code to the application function:
    [Raygun .sharedReporterWithApiKey("YOUR_APP_API_KEY")]

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 Raygun4MacOS initialization.

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

Symbolication

The macOS 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:

Native dSYM uploading app - Raygun Sidekick

The Raygun Sidekick is a native Mac 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.

Manual 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

where APP_NAME and BUILD_NUMBER make up the name of the zippped dSYM. The APP_ID is available in the URL of your app in the Raygun dashboard.

<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

Pulse

The setup instructions above will enable both Crash Reporting as well as Pulse, which logs Real User Monitoring analytics to your Raygun application dashboard. This information includes when your app starts and stops, which views your users navigate through, network calls that your app makes and any user details that you have provided.

Pulse messages will be sent to Raygun as soon as the app starts up. So once you've set up Raygun in your app, run it up and go to your Raygun Pulse dashboard to see the data it collects. Of course Pulse is most valuable once your app is out there being used by your users.

Network calls

Once enabled, Raygun4MacOS will automatically log the performance of network calls made with the following methods.

  • [NSURLSession dataTaskWithURL:]
  • [NSURLSession dataTaskWithURL:completionHandler:]
  • [NSURLSession dataTaskWithRequest:]
  • [NSURLSession dataTaskWithRequest:completionHandler:]
  • [NSURLSession downloadTaskWithURL:]
  • [NSURLSession downloadTaskWithURL:completionHandler:]
  • [NSURLSession downloadTaskWithRequest:]
  • [NSURLSession downloadTaskWithRequest:completionHandler:]
  • [NSURLSession uploadTaskWithRequest:fromData:]
  • [NSURLSession uploadTaskWithRequest:fromData:completionHandler:]
  • [NSURLSession uploadTaskWithRequest:fromFile:]
  • [NSURLSession uploadTaskWithRequest:fromFile:completionHandler:]
  • [NSURLConnection sendAsynchronousRequest:queue:completionHandler]
  • [NSURLConnection sendSynchronousRequest:returningResponse:error:]

Details about logged network calls can be found on the Performance tab of your Pulse dashboard.

Documentation missing?

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