Articles in this section

Unity Integration Guide

  • Updated

Backtrace's integration with Unity allows developers to capture and report log errors, handled and unhandled Unity exceptions, and native crashes to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.

Create a Backtrace instance for yourself at https://backtrace.io/create-unity - Once you log in, you can view a quick start for how to integrate with Unity in the Project Settings / Integration Guide page.

Download the backtrace-unity library from our GitHub location here or install it via OpenUPM.

Feature Summary

  • Lightweight library that quickly submits log errors, handled and unhandled exceptions, and native crashes to Backtrace
    • Supports wide range of Unity versions (2017.4+) and deployments (iOS, Android, Windows, Mac, WebGL, PS4/5 Xbox One/S/X, Nintendo Switch, Stadia)
    • Install via Universal Package Manager
  • Collect detailed context
    • Callstacks, including function names and line numbers where possible
    • System metadata including device GUID, OS version, memory usage, process age
    • Custom metadata including app version, scene info, device drivers
    • Last # log lines, screenshots, log or config files, other attachments
    • Android NDK Crashes; iOS Native Crashes, Windows Native Crashes
  • Client-side features
    • Client side filters and sampling controls
    • Deduplication options and custom client side fingerprintins
    • Offline crash capture/storage for future collection
    • Customizable event handlers and base classes
    • Performance statistics collection option for timing observability
  • Unity IDE integration to configure Backtrace behaviors in your game.

Prerequisites

Setup and Installation

  1. Make sure you have a Backtrace Instance already created.
  2. Install via OpenUPM or download the backtrace-unity zip file from our GitHub, unzip it, and keep the folder in a known location. 
  3. Open your Unity project
  4. Use the Unity Package Manager to install backtrace-unity (Window -> Package Manager -> Add Package From Disk). The Unity editor will refresh and the Backtrace Plugin should become available in the editor.
  5. Review your Project Settings / Integration Guide / Unity page in your xxx.sp.backtrace.io instance to see the specific URLs you can use in the Plugin to submit errors to your Backtrace instance.

Platforms Supported

Backtrace-unity has been tested and certified for games deployed on the following platforms:

  • Mobile - Android, iOS
  • PC - Windows, Mac
  • Web - WebGL
  • Game Consoles - PlayStation 4, PlayStation 5, Xbox One, Xbox Series X | S, Nintendo Switch, Google Stadia

There are some differences in capabilities that backtrace-unity provides based on the platform. Major capabilities are summarized as follows:

  • All Platforms - Unhandled Exceptions, Handled Exceptions, Custom Indexable Metadata, File Attachments*, Last N Log Lines, Automatic attachment of Screenshots, Client Side Deduplication Rules*, Client Side Submission Filtering, Client Side Submission Limits, Performance Diagnostics, Offline Database*(Except Nintendo Switch)
  • Android -Identified by attribute uname.sysname = Android; ANRs (Hangs), NDK crashes, Native Process and Memory Information, Out of Memory crashes, Java Exception Handler (Plugins, Exported Game in Android Studio)
  • iOS - Identified by attribute uname.sysname = IOS, Native iOS Crashes, Out of Memory crashes, Game Hangs.
  • WebGL - Identified by attribute uname.sysname = WebGL. The attribute device.model is currently used to share the browser information.
  • Switch - Identified by attribute uname.sysname = Switch. Note that the attribute GUID is regenerated with each Switch restart (It is not an accurate count of number of Users or Devices. It is a count of Switch Sessions). Note that the current release does no support Offline Database or related features.
    • Note - In your Backtrace Instance, please see Project Settings / Integration Guides / Game console portals to gain access to Native crashes from your Switch game via the developer portal.
  • PlayStation4 / PlayStation 5- Identified by attribute uname.sysname = PS4 / PS5
    • Note - In your Backtrace Instance, please see Project Settings / Integration Guides / Game console portals to gain access to Native crashes from your PS4 or PS5 game via the developer portal.
  • Xbox - Identified by usname.sysname = Windows NT. (Take a look at the module list to further identify Xbox related errors)
    • Note - In your Backtrace Instance, please see Project Settings / Integration Guides / Game console portals to gain access to Native crashes from your Xbox game via a GDX / XDK library or the Developer Portal.
  • Windows - Identified by attribute uname.sysname = Windows. Provides an option to capture Minidumps for Engine Crashes.
  • MacOS - Identified by attribute uname.sysname = MacOS.

Note: Unity allows you to disable stack trace information in player properties. As a result backtrace-unity, the call stack and the log lines section will be empty. 

Integrating into your Project

  1. Under the Assets Menu, there is now a Backtrace -> Configuration option. Choose that option to have a Backtrace Configuration is generated in the Assets folder.  
  2. Next, select an object from the Scene Hierarchy to associate the Backtrace reporting client to. In the example below, we use the _Manager object., Using the Inspector panel, click the Add Component button and search for the Backtrace Client object.
  3. Within the Backtrace Client panel, there is a Backtrace Configuration field. Drag and drop the Backtrace Configuration from the Assets folder to that field. More fields will appear for you to fill in to configure the Backtrace Client and Offline Database options.

Watch this 1 minute silent video to see the Integration and Configuration in action. The first 20 seconds of the video shows the above Integrating steps, and the second part shows details of the below Client and Database Settings.

Note: Please review details for the Server Address and Token fields below.

Backtrace Client and Offline Database Settings

The following is a reference guide to the Backtrace Client fields:

  1. Server Address: This field is required to submit exceptions from your Unity project to your Backtrace instance. The Server Address to use for your instance is provided in the Web Console under Project Settings -> Integration Guides -> Unity.
    NOTE: If Backtrace is hosting your instance, the Server Address will probably be based on https://submit.backtrace.io, and it will include your project name and submission token embedded in URL. Alternatively, you may see the Integration Guides provides a Server Address to .sp.backtrace.io:6098 . If this is the case, a separate Token field will also be provided.
  2. Token:  If your Server Address is https://submit.backtrace.io, then you do NOT need to enter a separate token here. If your Project Settings -> Integration Guides -> Unity page in the web console has a separate line for token, then copy that value here. 
  3. Reports per minute: Limits the number of reports the client will send per minutes. If set to 0, there is no limit. If set to a higher value and the value is reached, the client will not send any reports until the next minute. Further, the BacktraceClient.Send/BacktraceClient.SendAsync method will return false.
  4. Capture unhandled exceptions: Toggle this on or off to set the library to handle unhandled exceptions that are not captured by try-catch blocks.
  5. Enable Database: When this setting is toggled, the backtrace-unity plugin will configure an offline database that will store reports if they can't be submitted do to being offline or not finding a network. When toggled on, there are a number of Database settings to configure. 
  6. Backtrace Database path: This is the path to directory where the Backtrace database will store reports on your game. NOTE: Backtrace database will remove all existing files on database start
  7. Create database directory toggle: If toggled, the library will create the offline database directory if the provided path doesn't exists,
  8. Auto Send Mode: When toggled on, the database will send automatically reports to Backtrace server based on the Retry Settings below. When toggled off, the developer will need to use the Flush method to attempt to send and clear. Recommend that this is toggled on.
  9. Maximum number of records: This is one of two limits you can impose for controlling the growth of the offline store. This setting is the maximum number of stored reports in database. If value is equal to zero, then limit not exists, When the limit is reached, the database will remove the oldest entries.
  10. Maximum database size: This is the second limit you can impose for controlling the growth of the offline store. This setting is the maximum database size in MB. If value is equal to zero, then size is unlimited, When the limit is reached, the database will remove the oldest entries.
  11. Retry interval: If the database is unable to send its record, this setting specifies how many seconds the library should wait between retries. 
  12. Maximum retries: If the database is unable to send its record, this setting specifies the maximum number of retries before the system gives up.
  13. Retry order: This specifies in which order records are sent to the Backtrace server. 

Using in your C# code

You can further configure your game to submit crashes by making further changes in the C# code for your game. Include the following using statements to be able to use the library

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

Configuring specific try-catch blocks

If you setup Backtrace client and Backtrace database configuration you can retrieve database and client instances by using GameObject. When you retrieve client instance you can start sending reports from try/catch block in your game! The BacktraceClient.Send method will send an error report to the Backtrace endpoint specified.

//Read from manager BacktraceClient instance
var backtraceClient = GameObject.Find("_Manager").GetComponent();

 //Read from manager BacktraceClient instance
var database = GameObject.Find("_Manager").GetComponent();


try{
    //throw exception here
}
catch(Exception exception){
    var report = new BacktraceReport(exception);
    backtraceClient.Send(report);
}

BacktraceReport Options

The BacktraceReport class represents a single error report. You can  submit custom attributes using the attributes parameter, or attach files by supplying an array of file paths in the attachmentPaths parameter.

try
{
  //throw exception here
}
catch (Exception exception)
{
    var report = new BacktraceReport(
        exception: exception,
        attributes: new Dictionary<string, object>() { { "key", "value" } },
        attachmentPaths: new List() { @"file_path_1", @"file_path_2" }
    );
    backtraceClient.Send(backtraceReport);
}

Notes:

  • If you setup BacktraceClient with BacktraceDatabase and your application is offline or you pass invalid credentials to Backtrace server, reports will be stored in database directory path.

Attaching custom event handlers

Backtrace Client allows you to attach your custom event handlers. For example, you can trigger actions before the Send method:

 //Add your own handler to client API

backtraceClient.BeforeSend =
    (Model.BacktraceData model) =>
    {
        var data = model;
        //do something with data for example:        
        data.Attributes.Add("eventAtrtibute", "EventAttributeValue");
        if(data.Classifier == null || !data.Classifier.Any())
        {
            data.Attachments.Add("path to attachment");
        }

        return data;
    };

 
Backtrace Client currently supports the following events:

  • BeforeSend
  • OnClientReportLimitReached
  • OnServerResponse
  • OnServerError

Reporting unhandled application exceptions

BacktraceClient supports reporting of unhandled application exceptions not captured by your try-catch blocks. To enable reporting of unhandled exceptions even if you don't set this option in Backtrace configuration window use code below:

backtraceClient.HandleApplicationException();

Flush database

When your application starts, database can send stored offline reports. If you want to do make it manually you can use Flush method that allows you to send report to server and then remove it from hard drive. If Send method fails, database will no longer store data.

backtraceDatabase.Flush();

Clearing database

You can clear all data from database without sending it to server by using Clear method. BacktraceDatabase will remove all files and won't send it to server.

backtraceDatabase.Clear();

Advanced Topics

For more information on advanced features and architecture related details, please see the Readme on github - https://github.com/backtrace-labs/backtrace-unity/blob/master/README.md 

Investigating an Error in Backtrace

Once errors are being reported to your Backtrace instance, you should see them in your Triage and Web Debugger view. See below for a screenshot of the Triage view with some Unity exceptions reported.

 

The developer who is debugging the error may find it useful to view more details of Exception. They choose the 'View Latest Trace' action to see more details in the Backtrace Web Debugger. Below we can see a list of all attributes submitted with a report. (Note the yield signs are just an indicator that this value is not indexed in Backtrace). We can also see the call stack and details of the selected frame.

Below we see more details above the Environment Variables from the Web Debugger to further assist with investigation.

 

Related articles