Unity integration guide

Add Bugsnag to your Unity games and applications for iOS, Android, macOS, Windows and WebGL.

After completing this guide, exceptions and crashes from supported platforms are automatically detected and sent to Bugsnag.

Installation

  1. Download & Import the Bugsnag Unity Package

Download the latest Bugsnag Unity release, double click the Bugsnag.unitypackage file, and import into your Unity project.

Note: If your version of Unity supports 64-bit for Android, download Bugsnag-with-android-64bit.unitypackage.

Import Package

Basic configuration

  1. Create a Bugsnag GameObject

    Create a new GameObject called Bugsnag within your first scene via GameObject Menu -> Create Empty.

    Create GameObject

  2. Add the Bugsnag Component to Your GameObject

    Select the Bugsnag GameObject, and add the Bugsnag component via Component -> Scripts -> BugsnagUnity -> Bugsnag Behaviour

    Add Bugsnag Component

  3. Configure Your API Key

    Set the Bugsnag API key via the component inspector. You can find your API key on the Project Settings page on your Bugsnag dashboard.

    Set API Key

  4. Additional Setup (Android)

    If you target Android, set Internet Access to Require on the Android tab of the Unity Player Settings screen.

    Enable Internet Access

Code-only configuration

If it is not possible to add a Bugsnag GameObject using the Unity editor then Bugsnag can be initialized in code instead. Errors will only start being sent to Bugsnag after the call to Init has been made.

Bugsnag.Init("your-api-key-here");

Note: Bugsnag must be initialized from the main thread, such as in the Start() lifecycle function of a MonoBehaviour.

Showing full stacktraces

Uploading mapping files for Android

If you have enabled ProGuard or use the NDK, you will need to send mapping files to Bugsnag in order to deobfuscate Android stack traces. Adding the Bugsnag Gradle Plugin to your exported Gradle project will perform this task automatically.

Uploading debug symbol maps (dSYMs) for iOS

If you are using Bitcode, you will need to send dSYM files to Bugsnag in order to symbolicate native iOS stack traces. Our iOS symbolication guide provides details on how to automate this process.

Reporting unhandled errors

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Note: Native crashes will only be reported on iOS, macOS, and Android.

Reporting handled errors

If you would like to send non-fatal or handled exceptions to Bugsnag, you can pass any Exception object to Bugsnag’s Notify method in your Unity scripts:

Bugsnag.Notify(new System.Exception("Non-fatal"));

Bugsnag subscribes to the Unity logging framework messages. By default Unity log messages of type Exception will be sent as Bugsnag errors.

Debug.LogException(new System.Exception("Non-fatal"));

To configure which log levels will be reported as errors, see the NotifyLevel configuration option.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture and attach the following diagnostic data to every exception report:

  • A full stacktrace
  • Device model and OS version
  • Release stage (production, debug, etc)
  • The version of Unity used to build the application
  • Free disk space at the time the report is sent
  • A device- and vendor-specific identifier
  • Additional platform-specific information

Attaching custom diagnostics

It is often helpful to send us additional application-specific diagnostic data, for example the name of a subsystem in which an exception occurred. If you would like to add custom data to your Bugsnag error reports, you can use the Add method. Custom data is displayed inside tabs on each exception on your Bugsnag dashboard.

Bugsnag.Metadata.Add("system", new Dictionary<string, string>() {
  { "subsystem", "Player Mechanics" }
});

Use a callback with Notify to add or modify information in a specific report:

Bugsnag.Notify(new Exception(), report => {
  report.Context = "special context";
  report.Metadata.Remove("Unity");
  report.Metadata.Add("location", new Dictionary<string, string>() {
    { "region", "US" }
  });
});

To modify every report before it is sent to Bugsnag, use BeforeNotify:

Bugsnag.BeforeNotify(report => {
  report.Metadata.Add("account", ReadAccountInfo());
});

For more information on how to customize reports and what information can be modified, see Customizing error reports.

Logging breadcrumbs

In order to understand what happened in your application before each crash, it can be helpful to leave short log statements that we call breadcrumbs. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures common events such as:

  • Unity scene changes
  • Low memory warnings, network connectivity changes, and other device metrics on Android and iOS
  • Low-severity messages logged using Debug.Log
  • Prior non-fatal error events

Attaching custom breadcrumbs

Leaving breadcrumbs with a short message can be accomplished as follows:

Bugsnag.LeaveBreadcrumb("Player won");

When logging breadcrumbs, we’ll keep track of the timestamp, and show both the message and timestamp on your dashboard.

Additional data can be attached to breadcrumbs by using the longer form:

Bugsnag.LeaveBreadcrumb(
  "Button clicked",
  BreadcrumbType.Navigation,
  new Dictionary<string, string>() {{ "panel", panel.Name }}
);

Longer messages can be included as breadcrumb additional data:

Breadcrumbs.Leave("Rejected auth",
  BreadcrumbType.Log,
  new Dictionary<string, string> {{ "message", longMessage }}
);

Identifying users

Bugsnag helps you understand how many of your users are affected by each error. In order to do this, we send along a user ID with every exception. By default we will generate a unique ID and send this ID along with every exception from an individual device.

If you would like to override this identifier you can set the user ID property:

Bugsnag.User.Id = "userId";

You can also set the email and name of the user and these will be searchable in the dashboard:

Bugsnag.SetUser("userId", "user@example.com", "User Name");

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare crash rates between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default, but can be disabled by unchecking the box labeled “Auto Capture Sessions” in the configuration options:

Session tracking checkbox

If you want control over what is deemed a session, you can switch off automatic session tracking with the AutoCaptureSessions option, and manage the session lifecycle using StartSession(), StopSession() and ResumeSession().

Next steps

  • Explore a demo app
  • Get support for your questions and feature requests
  • View bugsnag-unity, the library powering this integration, on GitHub