Add Backtrace to your Unity project to automatically detect and report errors and crashes that occur in your game.
After you've completed the steps on this page, the Backtrace client will be installed and setup with the default configuration settings.
The Backtrace Unity SDK reports on the following types of errors:
- Log errors - Error messages in the console log. Logged by Debug.LogError (a variant of Debug.Log).
- Unhandled Exceptions - Exceptions that occur outside of an explicit try/catch statement.
- Handled exceptions - Exceptions that are explicitly caught and handled.
- Crashes - An end to the game play experience, where the game crashes or restarts.
- Hangs (mobile only) - Errors that occur when a game or an app is non-responsive.
- Out of memory crashes (mobile only) - Terminations of your game or app due to low memory conditions.
- Message reports - Error messages explicitly sent by the Backtrace client.
|Supported Platforms||Supported Systems|
|Game Consoles||PlayStation 4, PlayStation 5, Xbox One, Xbox Series X, Nintendo Switch, Google Stadia|
Offline database capabilities are currently not supported for Nintendo Switch.
What You'll Need
- A Backtrace account (log in or sign up for a free trial license).
- Your subdomain name (used to connect to your Backtrace instance). For example,
- A Backtrace project and a submission token.
- In the Backtrace Console, go to Project settings > Error submission > Submission tokens.
- Select +.
- Unity Editor version 2018.4 or higher
Player Configuration Settings
Backtrace supports the following player configuration settings for Unity:
- Scripting Backend: Mono or IL2CPP
- API Compatibility Level: .NET 4.0 or .NET Standard 2.0
Install the Backtrace Unity SDK
The following methods are available to install the Backtrace Unity SDK.
- Unity Package Manager
- Backtrace Hub
# Install openupm-cli
npm install -g openupm-cli
# Go to your Unity project directory
# Install the latest io.backtrace.unity package
openupm add io.backtrace.unity
For more information, see the installation steps on OpenUPM.
This installation method is supported for Unity 2018.3 or higher.
- Download the installer for the Backtrace Hub.
- Double-click to open the file.
- In the dialog for the Backtrace Hub Installer, click Install Now.
After the installation is complete, you can download the Backtrace Plugin from the Backtrace Hub.
- From the Backtrace Hub, for the Backtrace Plugin, click Install.
Initialize the Backtrace Client with GameObject
In this step, you create the Backtrace Configuration asset, create a new GameObject, add the Backtrace Client component to the GameObject, then add the Backtrace Configuration to the Backtrace Client component.
You can add the Backtrace Client component to any GameObject in your game scene.
Typically, the Backtrace Client component is added to a global GameManager or GameController object, given a descriptive name, and assigned a tag to identify it for scripting purposes.
- In your Unity project, go to Assets > Backtrace > Configuration.
- Go to GameObject > Create Empty.
- Enter a descriptive name for the new GameObject.
- In the Inspector, select Add Component.
- Search for “Backtrace”, then select Backtrace Client.
- From the Assets folder, drag the Backtrace Configuration file to the Backtrace configuration field.
Additional fields now display for the Backtrace client configuration and database configuration options.
To change Backtrace client and database options, we recommend to change these values in the Unity UI via Backtrace Configuration file. Alternatively, you can also make changes to the configuration in the C# code for your Unity project.
For more information about the available configuration options, see Configuration.
Configure the Server Address
The server address is required to submit exceptions from your Unity project to your Backtrace instance.
- In the Backtrace Console, go to Project Settings > Integration Guides > Unity.
- Copy the server address.
- Go back to the Backtrace Configuration in your Unity project.
- In the Server Address field, enter the server address in the following format:
- Provide the name of your subdomain and a submission token.
Verify the Setup
At this point, you've installed and setup the Backtrace client to automatically capture crashes and exceptions in your Unity game or app.
To test the integration, use a try/catch block to throw an exception and start sending reports.
//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("manager name").GetComponent<BacktraceClient>();
//Set custom client attribute
backtraceClient["attribute"] = "attribute value";
//Read from manager BacktraceClient instance
var database = GameObject.Find("manager name").GetComponent<BacktraceDatabase>();
//throw exception here
var report = new BacktraceReport(exception);