1. Home
  2. Language Guides
  3. Unity
  4. Crash Reporting
  5. Installation

Installation

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

Raygun4Unity has been tested to work on:

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

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

Step 1 - Installation

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

Step 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.

Step 3 - Send exceptions with RaygunClient

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("paste_your_api_key_here");
      raygunClient.Send(condition, stackTrace);
    }
  }
}

Step 4 - Release

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

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.

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

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);

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.

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";

The provider is open source and available at the Raygun4unity repository.

On this page: