Unity integration guide

Add Bugsnag to your Unity games and applications.

After completing this guide, exceptions in your JavaScript, C#, and Boo Unity code as well as native crashes on iOS and Android devices are automatically detected and sent to Bugsnag. We also detect crashes on tvOS, macOS and WebGL platforms.

Installation

  1. Download & Import the Bugsnag Unity Package

    Download the latest Bugsnag Unity release. Double click the .unitypackage file, then click the import button to import Bugsnag into your Unity project.

    Import Package

Basic configuration

  1. Create a Bugsnag GameObject

    Create a new GameObject within your first/main scene (GameObject Menu -> Create Empty), and rename it to Bugsnag.

    Create GameObject

  2. Add the Bugsnag Component to Your GameObject

    With your new GameObject selected, add the Bugsnag component (Component Menu -> Scripts -> Bugsnag).

    Add Bugsnag Component

  3. Configure Your API Key

    Finally, configure your Bugsnag API Key in 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)

    When building for Android, you’ll need to make sure that Internet Access is enabled. On the Android tab of the Unity Player Settings screen, make sure Internet Access is set to Require.

    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 Bugsnag.createBugsnagInstance has been made.

GameObject bugsnagObject = new GameObject("Bugsnag");
GameObject.DontDestroyOnLoad(bugsnagObject);
Bugsnag.createBugsnagInstance(bugsnagObject, "your-api-key-here");

Reporting unhandled errors

By default, Bugsnag will be notified about any exception logged to Debug.LogException. You can send additional log information to Bugsnag (eg. all Debug.LogError messages) by changing the Notify Level property in the Unity Inspector.

You can also change this setting in your scripts as follows:

Bugsnag.NotifyLevel = LogSeverity.Error;

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.InvalidOperationException("Non-fatal"));

Sending diagnostic data

It is often helpful to send us additional application-specific dianostic 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 AddToTab method. Custom data is displayed inside tabs on each exception on your Bugsnag dashboard.

Bugsnag.AddToTab("system", "subsystem", "Player Mechanics");
Bugsnag.AddToTab("location", "region", "US");

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 and at what interval.

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
  • Prior non-fatal error events

Attaching custom breadcrumbs

Leaving breadcrumbs can be accomplished as follows:

Bugsnag.LeaveBreadcrumb("Player won");
Bugsnag.LeaveBreadcrumb("Button was clicked");

By default, we’ll store and send the last 20 breadcrumbs you leave before errors are sent to Bugsnag. If you’d like to increase this number, you can call SetBreadcrumbCapacity

Bugsnag.BreadcrumbCapacity = 50;

NOTE: Breadcrumbs are not supported for WebGL deployments.

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 userId, for example to set it to be a username of your currently logged in user, you can set the userId property:

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

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

Next steps

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