Legacy 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-with-android-64bit.unitypackage file, and import into your Unity project.

Basic configuration

1. Create a BugSnag GameObject

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

   

2. Add the BugSnag Component to Your GameObject

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

   

3. Configure Your API Key

   Set the BugSnag API key via the Unity Inspector.

   

   You can find your API key in Project Settings from your BugSnag dashboard.

4. Additional Setup (Android)

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

   

Code-only configuration

BugSnag can be initialized in code if you don’t want to create a GameObject:

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

Errors will only start being captured after Bugsnag.Start() is called.

Showing full stacktraces

For Android or iOS projects in Unity follow the showing full stacktraces guide to set up ProGuard mapping, NDK symbols, and debug symbol maps (dSYMs) so you can see the original method names, file paths, and line numbers in stack traces.

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.

To disable automatic reporting of unhandled errors and native crashes, uncheck “Auto Detect Errors” in the Unity Inspector or if initializing in code, specify false for the AutoDetectErrors parameter:

Configuration config = new Configuration("your-api-key-here");
config.AutoDetectErrors = false;
Bugsnag.Start(config);

Reporting out-of-memory terminations

On iOS platforms, BugSnag automatically detects terminations of your app caused by the operating system due to high memory usage.

Reporting ANRs and fatal app hangs

When your app fails to respond to interactions in real time it causes user frustration and can lead them to abandon your app altogether.

Android

When the main thread of an Android app is blocked for too long, it appears unresponsive and the Android OS creates an Application Not Responding (ANR) error, presenting the user with a dialog option to force quit the app.

By default ANR detection is enabled.

See the AutoDetectAnrs configuration option for details.

iOS and macOS

An app hang or freeze is a specific instance of the main thread failing to respond in a reasonable amount of time and can be caused by performing CPU intensive work or performing blocking I/O on the main thread. If your app hangs for 10 seconds or longer, it may be terminated by the system watchdog as described in Apple’s documentation.

BugSnag automatically captures the stack trace of the main thread if an app hang is detected and ends with termination by the system watchdog or being force-quit by the user, helping you to identify the underlying cause.

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:

• Full stack traces for all threads.
• App state including running time and time in foreground.
• Build information including name, version/build and release stage.
• Device specification including model, OS version and total memory.
• System state including orientation, free memory, available disk space and battery level.

For more information see Automatically captured data.

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

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 Track Sessions” in the configuration options:

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

Identifying crashes at launch

By default BugSnag will identify crashes that occur whilst your app is launching, allowing you to prioritize fixing high-impact launch crashes.

Additionally you can use BugSnag to detect recurrent launch crashes: allowing you to take evasive action in your app, such as resetting data or turning off application features.

Follow the Identifying crashes at launch guide to configure this functionality.

Next steps

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