Unreal Engine integration guide

Add BugSnag to your UE4 and UE5 games and applications for Android, iOS, macOS and Nintendo Switch.

Installation

From the Unreal Engine Marketplace

1. Install the BugSnag plugin from the Unreal Engine Marketplace.

2. Enable the plugin from the Plugins window in Unreal Editor, available in the main menu under Edit → Plugins.

3. Select BugSnag under “Installed” plugins, and check the “Enabled” checkbox.

   

4. Click “Restart Now” to continue configuration.

5. Add “Bugsnag” to the list of dependencies in your game module’s .Build.cs file in order to allow interfacing with BugSnag from C++ code:

PrivateDependencyModuleNames.Add("Bugsnag");

From GitHub

1. Download the latest version (v2.0.0) of the BugSnag plugin from our GitHub releases page, choosing the correct package for the engine version used by your project.

2. Unzip the plugin into your project’s Plugins directory, creating one if necessary. Inside Plugins you should now have a Bugsnag directory that contains Bugsnag.uplugin.

3. Open your project in Unreal Editor and choose “Yes” when prompted to rebuild missing BugSnag and BugsnagEditor modules.

   

4. Ensure the BugSnag plugin is enabled in Unreal Editor’s Plugins window, available in the main menu under Edit → Plugins.

   

5. Add “Bugsnag” to the list of dependencies in your game module’s .Build.cs file in order to allow interfacing with BugSnag from C++ code:

PrivateDependencyModuleNames.Add("Bugsnag");

Nintendo Switch

To receive crash information from your Unreal Engine games running on Nintendo Switch, see our Nintendo Switch docs.

Basic configuration

Configure your API key through Unreal Editor’s Project Settings window, under Plugins → Bugsnag.

Or in Config/DefaultEngine.ini:

[/Script/Bugsnag.BugsnagSettings]
ApiKey=YOUR-API-KEY

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

Starting BugSnag manually

If you’d like control over when BugSnag starts, uncheck “Start Automatically” in Project Settings and BugSnag should be started either via BugSnag’s “Start” Blueprint or in code.

BugSnag can be started from a Blueprint by connecting an event to BugSnag’s “Start” action and providing your API key:

Alternatively BugSnag can be initialized in code:

#include "BugsnagFunctionLibrary.h"

UBugsnagFunctionLibrary::Start(TEXT("YOUR-API-KEY"));

When started manually, any configuration options inside Config/DefaultEngine.ini will still be applied.

If you’d like to configure BugSnag further, check out the Configuration options reference.

Blueprint support

You can also report handled errors, add user data, set context, log breadcrumbs, manually control sessions and control the launch period from Blueprints.

Showing full stacktraces

In order to see the original method names, file paths and line numbers in the stacktraces that are reported on your dashboard, certain symbol and mapping files need to be uploaded for each of your builds.

As part of the installation, this will be automatically configured for Android builds. However for iOS and macOS builds, some additional steps are required to upload debug symbols (dSYMs). See the showing full stacktraces guide for details.

Reporting crashes

After completing installation and basic configuration, crashes will be reported and automatically appear on your BugSnag dashboard.

Reporting ANRs

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.

ANR detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the EnabledErrorTypes configuration option.

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.

OOM detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the EnabledErrorTypes configuration option.

Reporting thermal kills

On iOS platforms, BugSnag detects terminations of your app by the operating system due to the device overheating.

Thermal kill detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the EnabledErrorTypes configuration option.

Reporting handled errors

If you would like to send non-fatal or handled errors to BugSnag, you can pass a name and description to BugSnag’s Notify function from your C++ code:

UBugsnagFunctionLibrary::Notify(TEXT("Non-fatal"), TEXT("Something went wrong"));

Adding diagnostics or adjusting severity

It can often be helpful to adjust the severity or attach custom diagnostics to handled errors. For more information, see Reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

BugSnag will automatically capture and attach the following diagnostic data to every error 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, total memory and GPU information.
• System state including orientation, free memory, available disk space and battery level.
• Unreal Engine information including engine version, current level and game state.

For more information see Automatically captured data.

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to BugSnag:

Configuration->AddOnSendError([](TSharedRef<IBugsnagEvent> Event)
{
    Event->AddMetadata(TEXT("account"), TEXT("name"), TEXT("Acme Co."));
    Event->AddMetadata(TEXT("account"), TEXT("paying_customer"), true);

    // Return `false` if you'd like to stop this error being reported
    return true;
});

For more information, see Customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information. BugSnag includes helpers for attaching an identifier, email address and name to reports that will be searchable in the dashboard.

By default we will generate a unique ID and send this ID along with every error report from an individual device. If you would like to override this identifier you can set the user ID property.

UBugsnagFunctionLibrary::SetUser(
    FString(TEXT("3")), // User ID
    FString(TEXT("bugs.nag@bugsnag.com")),
    FString(TEXT("Bugs Nag")));

For more information, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures common events including:

• Unreal Engine level and game state changes
• Low memory warnings, network connectivity changes, and other device metrics on Android, iOS and macOS
• Prior non-fatal error events

Leaving custom breadcrumbs

You can use the LeaveBreadcrumb method to log potentially useful events in your own applications:

UBugsnagFunctionLibrary::LeaveBreadcrumb(TEXT("Player won"));

BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard.

Additional data can also be attached to breadcrumbs by providing the optional type and metadata parameters. For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

Session tracking

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

Sessions are captured and reported by default. This behavior can be disabled using the AutoTrackSessions configuration option.

BugSnag will automatically report a session each time the app is launched or enters the foreground after being in the background for at least 30 seconds.

For more information about controlling session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

UBugsnagFunctionLibrary::AddFeatureFlag(TEXT("Checkout button color"), FString(TEXT("Blue")));
UBugsnagFunctionLibrary::AddFeatureFlag(TEXT("New checkout flow"));

For more information, see Feature flags & experiments.

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

• Get support for your questions and feature requests