Setup#

Add Cloud Diagnostics Advanced to your Unity project to automatically detect and report errors and crashes in your game.

After you've completed the steps on this page, the reporting client for Cloud Diagnostics Advanced installs and sets with the default configuration settings.

What you need#

You need a project and a submission token. You must have an active Cloud Diagnostics Advanced subscription to access token generation. By default, a submission token is generated for your project. If you need additional submission tokens, you can generate them as required.

To generate a submission token, go to your project in the Unity Dashboard and open the Cloud Diagnostics Advanced Diagnostic page.

From your dashboard project go to Products > Cloud Diagnostics Advanced > Diagnostic > Settings.

From Settings, go to > Error submission > Submission tokens, and select the Add (+) button.

Set up for non made with Unity solutions#

To use Cloud Diagnostics Advanced with the Unreal engine, see Unreal setup.

System requirements#

• Unity Editor version 2018.4 or higher
• Scripting Backend: Mono or IL2CPP
• API Compatibility Level: .NET 4.0 or .NET Standard 2.0

Migration from Cloud Diagnostics to Cloud Diagnostics Advanced#

If Cloud Diagnostics Advanced is purchased as an upgrade to Cloud Diagnostic, as part of the creation of your Organization in the new service, we import 90 days of data from the current Cloud Diagnostic instance. It’s possible to start using Cloud Diagnostics Advanced with your current data while you implement the SDK for the new service in your game.

The same information is still available in the Cloud Diagnostic dashboard.

Disable crash and exception reporting#

To use Cloud Diagnostics Advanced, you need to replace the implementation of Cloud Diagnostic. Make sure the Crash and Exception Reporting service is disabled:

1. Open your project in the Unity Editor.
2. From the Unity Editor menu, select Window > General > Services to open the Services window.
3. From the Services window, select Cloud Diagnostics.
4. Use the toggle beside Crashes and exceptions to turn off the service.

Install SDK#

To use the full features of Cloud Diagnostic Advanced, you need to install the Backtrace Unity SDK.

The following methods are available to install the Backtrace Unity SDK.

OpenUPM#

Install openupm-cli#

npm install -g openupm-cli

Go to your Unity project directory#

cd YOUR_UNITY_PROJECT_DIR

Install the latest io.backtrace.unity package#

openupm add io.backtrace.unity

Unity package manager#

1. Download the latest version of the Backtrace Unity SDK from GitHub.
2. Unzip the package and save it locally.
3. Open your project in the Unity Editor.
4. From the Unity Editor menu, select Window > Package Manager.
5. Complete the steps in Installing a package from a local folder in the Unity documentation.

Git#

This installation method is supported for Unity 2018.3 or higher.

1. Clone the source project’s Git URL.
2. Open your project in the Unity Editor.
3. From the Unity Editor menu, select Window > Package Manager.
4. Complete the steps in Installing from a Git URL in the Unity documentation.

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.

1. Open your project in the Unity Editor.
2. From the Unity Editor menu, select Assets > Backtrace > Configuration. (Note: if no Backtrace option appears under Assets then close and reopen the project, and confirm the package is installed correctly.)
3. Go to GameObject > Create Empty.
4. Enter a name for the new GameObject.
5. In the Inspector, select Add Component.
6. Search for “Backtrace”, then select Backtrace Client.
7. 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 that you change these values in the Unity UI with the 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 errors and crashes to your Cloud Diagnostics Advanced instance.

Obtaining your server address#

From your dashboard project go to Products > Cloud Diagnostics Advanced > Diagnostic > Settings.

From Settings, go to > Error submission > Submission tokens.

To obtain the server address for a token, open the More (⋮) menu next to the Enabled toggle, then select Copy server address to copy it to your clipboard.

Configuring your Unity Editor project#

1. Open your project in the Unity Editor.
2. Select the Backtrace Configuration asset.
3. In the Server Address field, enter the URL for the server address.

Verify the setup#

At this point, you installed and set up the Backtrace client to automatically capture crashes and exceptions in your Unity game. To test the integration, use a try/catch block to throw an exception and start sending reports.

First, include the Backtrace dependencies:

using Backtrace.Unity; using Backtrace.Unity.Model;

In an appropriate location such as the Start method of a new script, use the following to verify the setup:

//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>();
try {
    //throw exception here
}
catch(Exception exception) {
    var report = new BacktraceReport(exception);
    backtraceClient.Send(report);
}