Unity integration guide

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

After completing this guide, exceptions and crashes are automatically detected and sent to Bugsnag in iOS, Android, macOS, and WebGL games.

Installation

  1. Download & Import the Bugsnag Unity Package

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

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 Menu -> Scripts -> Bugsnag.

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

Session tracking

Bugsnag can automatically track app sessions and record the number of handled/unhandled errors. This functionality is disabled by default, but can be enabled by checking the box labeled “Track sessions” in the configuration options:

Session tracking checkbox

If configuring in code, set the auto-capture configuration option to true when creating your Bugsnag instance:

Bugsnag.createBugsnagInstance(bugsnagObject, "your-api-key-here", true);

To manually start a session, use the StartSession function:

Bugsnag.StartSession();

Starting a new session will automatically end the previous one. Manual sessions will be captured whether automatic session capture is enabled or not.

Next steps

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