Unity

Raygun4Unity - Unity Error Monitoring & Crash Reporting

Raygun4unity allows you to setup real time error monitoring and crash reporting for your Unity games.  

Supported platforms

Raygun4Unity has been tested to work on:

  • Windows Desktop
  • Windows Phone
  • Mac
  • iOS
  • Android

Namespace

The main classes can be found in the Mindscape.Raygun4Unity namespace.

Setup instructions

1. Download the library

Download raygun4Unity.[version].zip from the latest release listed on Github. Extract the contents and paste the raygun4Unity folder somwhere into the Assets directory of your game.

2. Listen to Application.logMessageReceived

If you haven't done so already, listen to Application.logMessageReceived in a C# script. Attach this script to a GameObject that will be used when your game is loaded.

3. Use the RaygunClient to send exception reports

To send exception messages to your Raygun application, create an instance of the RaygunClient by passing your application API key into the constructor. Then call one of the Send methods. There are 3 different types of exception data that you can use in the Send methods:

  • Strings provided by Unity for the error message and stack trace.
  • Exception .Net objects. Useful if you need to send handled exceptions in try/catch blocks.
  • RaygunMessage Allowing you to fully specify all the data fields that get sent to Raygun.

In the following example, Application.logMessageReceived has been hooked up in a MonoBehaviour that will be run during the initialization process of the game. In the handler, you can check to see if the type of the log is an exception or error to determine what to report to Raygun. Alternatively, you could send all types of log messages.

using Mindscape.Raygun4Unity;
using UnityEngine;

public class Logger : MonoBehaviour
{
  void Start()
  {
    Application.logMessageReceived += Application_logMessageReceived;
  }

  private void Application_logMessageReceived(string condition, string stackTrace, LogType type)
  {
    if (type == LogType.Exception || type == LogType.Error)
    {
      RaygunClient raygunClient = new RaygunClient("YOUR_APP_API_KEY");
      raygunClient.Send(condition, stackTrace);
    }
  }
}

Affected user tracking

To keep track of how many users are affected by each exception, you can set the User or UserInfo property of the RaygunClient instance. The user can be any id string of your choosing to identify each user. Ideally, try to use an id that you can use to relate back to an actual user such as a database id, or an email address. If you use an email address, the users gravitars (if found) will be displayed on your Raygun error dashboards. Below is an example of setting the User property:

raygunClient.User = "user@email.com";

The UserInfo property lets you provide additional user information such as their name:

raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties. The only required field is Identifier.

  • Identifier is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank, as we will use the identifier as the email address if it looks like one, and no email address is not specified.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags and custom data

A couple of Send method overloads allow you to attach a list of tags and a dictionary of key-value custom data to the exception report. Tags and custom data get displayed on each report in Raygun. Either of these can be null if you only want to send one or the other.

The following overload is for when sending the message and stacktrace strings as provided by Unity in the HandleException callback.

var tags = new List() { "Level 6", "0 lives"};
var customData = new Dictionary() { {"Difficulty", "Very-Hard"} };
raygunClient.Send(message, stacktrace, tags, customData);

Another overload is available for when sending a .NET Exception object.

var tags = new List() { "Level 6", "0 lives"};
var customData = new Dictionary() { {"Difficulty", "Very-Hard"} };
raygunClient.Send(exception, tags, customData);

Message modifcations before sending

By listening to the RaygunClient.SendingMessage event, you can make modifications to any part of the message just before it is serialized and sent to Raygun. Setting e.Cancel = true will prevent Raygun4Unity from sending the message. This is useful for filtering out types of exceptions that you don't want.

Application/Game version

The current version of raygun4Unity does not automatically obtain the game version number. You can however specify this by setting the ApplicationVersion property of the RaygunClient instance.

raygunClient.ApplicationVersion = "1.3.37.0";

Documentation missing?

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