Demystifying the Raygun4Apple provider: A technical deep dive

We’ve been making changes to how we support Apple platforms now and in the future. The result of these changes is a brand new provider called Raygun4Apple.

In this post, we will explain what’s different about the Raygun4Apple provider and why we decided to create it.

We will also provide a short guide on how to transition from our previous Apple platform providers to the new Raygun4Apple provider.

What is Raygun4Apple?

It is our latest provider to support integrating Raygun into your applications running on iOS, tvOS, and macOS. We’ve redesigned the API from our previous Apple platform providers to make it easier to understand and use within your projects.

We previously only supported the iOS and macOS platforms with a separate provider for each, Raygun4iOS and Raygun4OSX. While our Raygun4iOS provider received fixes and updates, those changes did not always find a way to the other provider Raygun4OSX.

However, the new Raygun4Apple provider now has a shared code base. That means when we create fixes and updates, they are available for all platforms at once! All of our future support for Apple platforms will come as updates to the Raygun4Apple provider.

But what exactly is a provider?

Providers are software components (e.g., a Ruby Gem or a .NET Assembly) which integrate with your software to facilitate the capture and delivery of information to Raygun.

In this case, Raygun4Apple is a framework you can reference in your Xcode projects to get access to APIs that facilitate capturing and delivering information to Raygun.

What makes up a provider?

The providers we create for Apple platforms can be broken down into three essential parts.

1. Raygun Client

As a Raygun customer, you use the API to configure sending data to Raygun. The main entry for integrating with Raygun is through the RaygunClient class. We expose a variety of functionality through this class to allow you to configure how Raygun interacts with your application.

2. Crash Recorder

The Crash Recorder is an internal library used by the Raygun Client to record native exception information and generate crash reports. It is common practice for crash reporting providers to make use of open-sourced libraries for crash recording functionality.

3. Apple OS

The Apple OS (Operating System) is the system software that manages the resources of the devices and provides other programs access to hardware functionality. Raygun4Apple currently supports three operating systems; iOS, tvOS, and macOS.

What has changed?

We have now changed the crash recorder library we were using within our previous Apple platform providers. The last open-source library we had been using was the Plausible CrashReporter otherwise known as PLCrashReporter.

The PLCrashReporter library served us well with our previous providers Raygun4iOS and Raygun4OSX. Unfortunately, PLCrashReporter’s last stable public release was made in 2014. Moving forward, we needed a library that was still actively supported.

For us to also support the latest Apple platforms, we had to look for a new crash recorder library. We settled upon using KSCrash, which provides better crash recording support and is still actively worked upon. KSCrash also has support for the latest Apple platforms and allowed us to expand our support to include tvOS.

So why make a new provider and not update the old providers?

The crash recorder is a fundamental component which affects the implementation of many features within the provider. So changing this component would always end up being a fundamental rewrite of the providers.

This presented an opportunity to improve the usability and capability of our providers. We wished to revisit our provider syntax to make it easier to use and understand.

There was also an opportunity to reuse a lot of code since it is written in the same language and is mainly platform independent. This way if we add a new feature or fix, the code is quickly and easily released to every platform supported by Raygun4Apple. It made sense then to rewrite the provider and have it placed under a new title: Raygun4Apple.

Why should I use the Raygun4Apple provider?

Beyond the improved crash recorder, we have also added some other improvements. We’ve added support for tvOS, and we are also in a better position to support more Apple platforms in the future like watchOS.

The Breadcrumbs feature is now available for all platforms as well as improved Swift support making our API inter-operate better from Objective-C to Swift.

Our new crash recorder (KSCrash) is a modern crash recorder that allows us to capture a variety of errors and crashes including:

• Mach kernel exceptions
• Fatal signals
• C++ exceptions
• Objective-C exceptions
• Custom crashes (e.g., from scripting languages)

That’s great! How do I start using the Raygun4Apple provider?

If you have not integrated Raygun before, you can go straight to our Crash Reporting documentation or our Real User Monitoring documentation to find out how.

Otherwise here is a quick overview of the changes you can expect to make to your current integration of Raygun.

To start, you’ll need to remove the Raygun4iOS.framework or Raygun4OSX.framework from the Linked Frameworks and Libraries section in the General window of the Project view.

Secondly, download and install the Raygun4Apple package onto your Mac computer. Navigate to the framework’s installed directory at /Library/Frameworks/raygun4apple. Drag the appropriate framework for your projects platform into the Embedded Binaries section of the General tab of the Project view.

Then, replace the import dependencies and setup snippets found in your AppDelegate class using the following instructions.

Remove the following:

[Raygun sharedReporterWithApiKey:@"YOUR_APP_API_KEY" withCrashReporting:true];
[Raygun.sharedReporter attachPulse];
[Raygun.sharedReporter attachPulseWithNetworkLogging:true];

Add the following:

RaygunClient *raygunClient = [RaygunClient sharedInstanceWithApiKey:@"YOUR_APP_API_KEY"];
[raygunClient enableCrashReporting];
[raygunClient enableRealUserMonitoring];
[raygunClient enableNetworkPerformanceMonitoring];

Find and replace any calls to Raygun when manually recording errors or events.

Find and remove the following:

[Raygun.sharedReporter send:[NSException exceptionWithName:NSGenericException reason:@"Something went wrong" userInfo:nil]];
// or
[Raygun.sharedReporter sendPulseTimingEvent:ViewLoaded withName:@"MyAppViewController" withDuration:300];

Replace with the following:

[RaygunClient.sharedInstance sendException:[NSException exceptionWithName:NSGenericException reason:@"Something went wrong" userInfo:nil]];
// and
[RaygunClient.sharedInstance sendTimingEvent:RaygunEventTimingTypeViewLoaded withName:@"MyAppViewController" withDuration:300];

And that’s it!

We are continually improving our support for Apple platforms, so if you would like to request any features, visit our feature request forum.

Do you have questions about the new Raygun4Apple provider? Get in touch with a friendly team member.