Setting Up Backtrace for Unreal Engine

Add Backtrace to your Unreal Engine project to automatically detect and report native crashes that occur in your game.

Backtrace supports Unreal Engine's Crash Reporter, therefore installation of a Backtrace SDK is not required to capture crashes.

Features

The Backtrace Unreal plugin reports on the following types of errors:

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.

Supported Platforms

Supported Platforms	Supported Systems
Mobile	Android, iOS
PC	Windows, MacOS, Linux
Game Consoles	PlayStation 4, PlayStation 5, Xbox One, Xbox Series X, Xbox Series S, Nintendo Switch

note

For on-premise (self-hosted) users, the integration for Unreal Engine requires specific packages. For more information, contact support.

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, https://example-subdomain.sp.backtrace.io.
A Backtrace project and a submission token.

Generate a Submission Token

In the Backtrace Console, go to Project settings > Error submission > Submission tokens.
Select +.

System Requirements

Unreal Engine version 4.16 to 5.0

Enable the Crash Reporter

In the Unreal Editor, go to Edit > Project Settings.
In the Project Settings, search for "crash reporter".
Under Packaging, enable Include Crash Reporter.

note

If you're building from the command line, add the -crashreporter flag.

Initialize the Backtrace Client

For Crashes in the Editor

In the root directory for your Unreal Engine project, open the Config folder.
Copy the DefaultEngine.ini file and paste it into the Engine > Config folder.
note
If the Engine folder doesn't exist at the root directory for your Unreal Engine project, create a new folder and name it Engine. Then in the Engine folder, create another folder and name it Config.
Rename the file to UserEngine.ini.

Open the UserEngine.ini file and add the following lines:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"

For the DataRouterUrl, provide the name of your subdomain and a submission token.

When your app or game crashes in the Unreal Editor, the Unreal Engine Crash Reporter dialog will appear and allow you to send the crash report to your Backtrace instance.

For Crashes in Packaged Builds

You can configure the crash reporter to be the default for all packaged builds or for a single packaged build.

To configure the crash reporter as the default for all packaged builds:

In the root directory for your Unreal Engine project, open the Config folder.
Copy the DefaultEngine.ini file and paste it into the following directory: [UNREAL_ENGINE]/UnrealEngine/Engine/Programs/CrashReportClient/Config
note
The directory could also be under C:/Program Files/Epic Games/UE_[version]. You can also search your system for 'CrashReportClient' to find it.

Open the DefaultEngine.ini file and add the following lines:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"

For the DataRouterUrl, provide the name of your subdomain and a submission token.

To configure the crash reporter for a packaged build:

In the root directory for your Unreal Engine project, open the Config folder.
Copy the DefaultEngine.ini file and paste it into the following directory:
- For Unreal Engine 4.25 and earlier: [BUILD_DIRECTORY]/WindowsNoEditor/Engine/Programs/CrashReportClient/Config/NoRedist
- For Unreal Engine 4.26 and higher: [BUILD_DIRECTORY]/WindowsNoEditor/Engine/Restricted/NoRedist/Programs/CrashReportClient/Config
  note
  Create the subdirectories if they do not exist.

Open the DefaultEngine.ini file and add the following lines:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"

For the DataRouterUrl, provide the name of your subdomain and a submission token.

Integrate the backtrace-android error reporting library with your Unreal Engine game for Android written in Java or Kotlin.

Download BacktraceAndroid_UPL.xml.

In the BacktraceAndroid_UPL.xml file, provide the name of your subdomain and a submission token for BacktraceCredentials.

Java:

BacktraceCredentials credentials = new BacktraceCredentials("https://submit.backtrace.io/{subdomain}/{submission-token}/json");

Kotlin:

val backtraceCredentials = BacktraceCredentials("https://submit.backtrace.io/{subdomain}/{submission-token}/json")

In the directory for your Unreal Engine project, locate your app or game's Build.cs file.
Place the BacktraceAndroid_UPL.xml file in the same directory with the Build.cs file.

In the Build.cs file, add the following lines at the end of the ModuleRules class constructor:

if (Target.Platform == UnrealTargetPlatform.Android)
{
  string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
  AdditionalPropertiesForReceipt.Add("AndroidPlugin", System.IO.Path.Combine(PluginPath, "BacktraceAndroid_UPL.xml"));
}

Download the BacktraceWrapper.h header file and add it to your GameInstance.
To initialize the Backtrace client, use BacktraceIO::FInitializeBacktraceClient.
note
It's recommended to initialize the client from the GameInstance::OnStart() method. However, if the method is not available, you can initialize the client with any method you use to start your app or game process.
note
Optionally, you can specify custom attributes and file attachment paths to submit with your error reports. If you choose to specify file attachment paths, they must be specified as Android paths. For example, to specify a file attachment path for your ProjectSavedDir(), use:
if (Target.Platform == UnrealTargetPlatform.Android) #include "Misc/App.h" #if PLATFORM_ANDROID extern FString GFilePathBase; FString FileAttachmentPath = GFilePathBase + FString("/UE4Game/") + FApp::GetName() + TEXT("/") + FApp::GetName() + TEXT("/Saved") + TEXT("MyFileName.txt"); #endif
For more details on how to convert your Unreal Engine paths to Android paths, see the conversion functions for FAndroidPlatformFile::PathToAndroidPaths in the AndroidPlatformFile.cpp file.

To change the default configuration settings for the Backtrace client, you can change the settings in the BacktraceAndroid_UPL.xml file. For more information, see Configuring Backtrace for Android for the backtrace-android library.

Integrate the backtrace-cocoa error reporting library with your Unreal Engine game for iOS written in Swift or Objective-C.

From Assets, download and extract the Backtrace.framework.zip and the Backtrace_PLCrashReporter.framework.zip files.
Copy and paste the Backtrace.framework.zip and the Backtrace_PLCrashReporter.framework.zip folders into the directory for your Unreal Engine project.
Locate your app or game's Build.cs file.

In the Build.cs file, add the following lines at the end of the ModuleRules class constructor:

if (Target.Platform == UnrealTargetPlatform.IOS)
{
  PublicAdditionalFrameworks.AddRange(
    new Framework[]
  {
    new Framework("Backtrace", "/Library/Frameworks/Backtrace.framework", "", true),
    new Framework("Backtrace_PLCrashReporter", "/Library/Frameworks/Backtrace_PLCrashReporter.framework", "", true)
  }
    );
}

note

Make sure to reflect the path to where you've placed both frameworks within your game project.

To initialize the Backtrace client, use the following to import Backtrace-Swift.h from Backtrace.framework/Headers:

#if PLATFORM_IOS
#import <Backtrace/Backtrace-Swift.h>
#endif

void UYourGameInstanceBase::OnStart()
{
#if PLATFORM_IOS

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
        initWithSubmissionUrl: [NSURL URLWithString: @"https://submit.backtrace.io/{subdomain}/{submission-token}/plcrash"]];
BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                                  initWithCredentials: credentials
                                                  dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                                  reportsPerMin: 3
                                                  allowsAttachingDebugger: NO
                                                  detectOOM: TRUE];
BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];
#endif
}

For the initWithSubmissionUrl, provide the name of your subdomain and a submission token.

For information on how to change the default configuration settings for the Backtrace client, see Configuring Backtrace for iOS.

Upload Debug Symbols

You must now ensure your build environment has been configured to generate debug symbols, which can then be uploaded to your Backtrace instance, a connected Symbol Server, an Amazon S3 bucket, or a Google Cloud storage bucket.

For information on how to generate symbols, see Symbolication.

Verify the Setup

At this point, you've installed and setup the Backtrace client to automatically capture crashes in your Unreal Engine game or app.

To test the integration, send a crash report to your Backtrace instance.

To crash your game when it starts, create a class called MyActor and reference a blueprint. The blueprint can be attached to the BeginPlay event.

The header file (which has the .h extension) contains the class definitions and functions, while the implementation of the class is defined by the .cpp file. For example:

MyActor.h:

// Fill out your copyright notice in the Description page of Project Settings.
​
#pragma once
​
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "GenericPlatform/GenericPlatformCrashContext.h"
#include "MyActor.generated.h"
​
UCLASS()
class BACKTRACE_API AMyActor : public AActor
{
    GENERATED_BODY()

public:
    // Sets default values for this actor's properties
    AMyActor();
​
protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;
​
public:
    // Called every frame
    virtual void Tick(float DeltaTime) override;
​
    UFUNCTION(BlueprintCallable, Category = "Backtrace Tools")
        void DoCrashMe();
​
};

MyActor.cpp:

// Fill out your copyright notice in the Description page of Project Settings.
​
​
#include "MyActor.h"
​
// Sets default values
AMyActor::AMyActor()
{
    // Set this actor to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = true;
​
}
​
// Called when the game starts or when spawned
void AMyActor::BeginPlay()
{
    Super::BeginPlay();
    {
​
            FGenericCrashContext::SetGameData(TEXT("BluePrintCallStack"), TEXT("BluePrintCallStackValue"));
    }

}
​
// Called every frame
void AMyActor::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);
​
}
​
void AMyActor::DoCrashMe()
{
​
    UE_LOG(LogTemp, Fatal, TEXT("I crash and burn. Bye bye now"));
​
}

Java:

try {
  // throw exception here
}
catch (Exception exception) {
  backtraceClient.send(new BacktraceReport(e));
}

Kotlin:

try {
  // throw exception here
}
catch (e: Exception) {
  backtraceClient.send(BacktraceReport(e))
}

Swift:

import UIKit
import Backtrace

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  var window: UIWindow?

  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

      let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!,
                                                      token: "token")
      BacktraceClient.shared = try? BacktraceClient(credentials: backtraceCredentials)

      do {
          try throwingFunc()
      } catch {
          BacktraceClient.shared?.send { (result) in
              print(result)
          }
      }

      return true
  }
}

Objective-C:

#import "AppDelegate.h"
@import Backtrace;

@interface AppDelegate ()

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                       initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                       token: @"token"];
  BacktraceClient.shared = [[BacktraceClient alloc] initWithCredentials: credentials error: nil];

  // sending NSException
  @try {
      NSArray *array = @[];
      NSObject *object = array[1]; // will throw exception
  } @catch (NSException *exception) {
      [[BacktraceClient shared] sendWithException: exception completion:^(BacktraceResult * _Nonnull result) {
          NSLog(@"%@", result);
      }];
  } @finally {

  }

  return YES;
}

@end

Features​

Supported Platforms​

What You'll Need​

System Requirements​

Enable the Crash Reporter​

Initialize the Backtrace Client​

For Crashes in the Editor​

For Crashes in Packaged Builds​

Upload Debug Symbols​

Verify the Setup​

Features

Supported Platforms

What You'll Need

System Requirements

Enable the Crash Reporter

Initialize the Backtrace Client

For Crashes in the Editor

For Crashes in Packaged Builds

Upload Debug Symbols

Verify the Setup