Skip to main content

Unreal Integration Guidelines


This document applies to CrashSight SDK 4.2.x version. For 4.3.x version, please refer to new version of Unreal SDK Integration Document

1 Integration in Unreal

1.1 Import CrashSight UE Plugin

    1. After creating a project on the platform, the SDK that matches the platform and engine of the project can be downloaded from the "Tutorial" in the sidebar, as shown in the figure below:

    1. Unpack Plugins files under the same directory. Copy the CrashSight directory in the Plugins folder to the Plugins directory under the UE project's root directory (if the folder doesn't exist, create it). Click [file] to refresh [Visual Studio project], then you will see CrashSight plugin code and directory structure in the Visual Studio project, as shown in the image.

    1. Compile CrashSight plugin source code and project source code together. When done, you can see the CrashSight plugin on the plugin editing page of UE editor, as shown in the image.

1.2 Add CrashSight to the dependencies

Add the following to Build.cs in the main project module:

PrivateDependencyModuleNames.AddRange(new string[] { "CrashSight" });

1.3 Execute Initialization

1.3.1 Android&iOS

  • About the method: Choose the first scene or the main scene, and call the following code in a script loaded as early as possible to initialize:
#include "CrashSightAgent.h" //Please include this header file
#if DEBUG
CrashSightAgent::ConfigDebugMode (true);
#endif
// Set the domain name for reporting. Please fill in according to project publishing requirements. (required)
CrashSightAgent::ConfigCrashServerUrl("UploadUrl");
// Set the target APP ID for reporting and initialize. You can find the APP ID from More->Product Settings->Product Info of the management console. (required)
CrashSightAgent::InitWithAppId("AppID");

  • Domain name for reporting

Local(China) public cloud:

International public cloud:

1.3.2 Windows

  • About the method: Choose the first scene or the main scene, and call the following code in a script loaded as early as possible to initialize:
#include "CrashSightBridgeWin.h" //Please include this header file

CrashSight::CrashSightBridge::InitContext(UserId, AppVersion, CrashSightAppKeyForWindows);
// UserId and AppVersion can be decided by yourself according to your needs.

Windows platform also needs to add crash capture configuration. There are two options for crash capture configuration. For projects that can modify the engine, it is strongly recommended to use the solution in 1.3.2.1, which will provide more accurate crash reporting. For other users using the official engine version, use the configuration in 1.3.2.2.

1.3.2.1 Solution A
  1. Copy CrashSightReporter.h into the engine source code \Engine\Source\Runtime\Core\Public\Windows directory
  2. Introduce CrashSightReporter.h into the engine source code\Engine\Source\Runtime\Core\Private\Windows\WindowsPlatformCrashContext.cpp, and in the first line of the function ReportCrash (DefaultReportCrash under some macro configurations), call FCrashSightReporter::ReportCrashToCrashSight( ExceptionInfo);
  3. Compile the engine
  4. After initializing with the function CrashSight::CrashSightBridge::InitContext, call CrashSight::CrashSightBridge::SetVehEnable(false)
1.3.2.2 Solution B
  1. Call CrashSight::CrashSightBridge::SetVehEnable(true) after initializing with the function CrashSight::CrashSightBridge::InitContext
  2. Call CrashSight::CrashSightBridge::UnrealCriticalErrorEnable(true) after CrashSight::CrashSightBridge::SetVehEnable(true)

After the project is packaged, create CrashSightConfig64.dat file in the same level directory as CrashSight64.dll. There are three parameters to be updated in the CrashSightConfig64.dat file: 1)GameName 2)Reported URL 3)APPID

<CrashSightConfig __version="1">
<GameName>Test-Game.exe</GameName>
<LobbyName></LobbyName>
<IgnoreDllCnt>2</IgnoreDllCnt>
<IgnoreDlls>TenSLX.dll</IgnoreDlls>
<IgnoreDlls>Tensafe.dll</IgnoreDlls>
<AppId>0620edc732</AppId>
<DomainUrl>pc.crashsight.wetest.net</DomainUrl>
<LogOutput>0620edc732</LogOutput>
</CrashSightConfig>

The <LogOutput> line is a debug logging switch that, when added, generates a CrashSightLog directory in the same directory as CrashSight64.dll, which holds CrashSight's runtime logs. Please remove this line before release.

1.4 Crash Reporter Client Integration

The Crash Reporter Client is a crash reporting mechanism that comes with the Unreal Engine and is capable of catching and reporting crashes independently. To report crashes through the Crash Reporter Client, locate DefaultEngine.ini in your project's Config directory and add:

[CrashReportClient]
CrashReportClientVersion=1.0
DataRouterUrl=“https://pc.crashsight.qq.com/csApi/ueCrc/exception/{APPID}/{VERSION}”

If there is already a [CrashReportClient] block, only the contents need to be modified. Then, go to Project Settings->Packaging->Advanced and check Include Crash Reporter. Crash Reporter Client's crash reporting mechanism is completely independent to the CrashSight SDK。 It can be integrated separately and can provide some field information unique to the Unreal engine. However, the Crash Reporter Client only reports crashes and does not include important features such as error reporting. In addition, Crash Reporter Client can only set one DataRouterUrl, which means that CrashSight and other crash reporting tools cannot use Crash Reporter Client at the same time.

3 Interfaces

3.1 Initialization

public static void InitWithAppId (string appId)

Note: Execute initialization. Initialize as early as possible to enable crash detection and reporting features.

ParameterTypeNote
appIdstringAPP ID of registered projects

3.2 Enabling Switch for Debugging

public static void ConfigDebugMode (bool enable)

Note: Whether to enable debugging mode. Off by default. After enabling, some logs will be printed, but it can help locate issues during tests.

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
enableboolEnabling switch for debugging

3.3 Set Domain Name for Reporting

public static void ConfigCrashServerUrl (const char * crashServerUrl)

Note: Set domain name for reporting. Note: Call it before the InitWithAppId interface. The domain name of local(China) public environment is as follows:

A direct CrashSight domain name Integration is different from an indirect one using MSDK. Make sure you follow the above domain name to reconfigure. For other environment domain name, please consult the Integration contact.

ParameterTypeNote
crashServerUrlconst char *Target domain name of reporting

3.4 Set Custom Log Reporting Level

public static void ConfigCrashReporter (int logLevel)

Note: Set custom log reporting level. Off=0, Error=1, Warn=2, Info=3, Debug=4

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
logLevelintLog level

3.5 Set Channel, App Version, User ID, Lazy Initialization

static void ConfigDefault (const char *channel, const char *version, const char * user, long delay);

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
channelconst char *Channel
versionconst char *App Version
userconst char *User ID
delaylongDelay(s)

3.6 Set Android Device ID

public static void SetDeviceId(const char *deviceId)

Note: Starting from version 4.2.9, CrashSight Android no longer obtains AndroidId, and uses uuid as device ID by default

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
deviceIdconst char *Device ID

3.7 Set Android Phone Model

public static void SetDeviceModel(const char *deviceModel)

Note: Set phone model

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
deviceModelconst char *Phone model

3.8 Error Reporting

public static void ReportException(int type, const char * name, const char * reason, const char * stackTrace, const char * extras, bool quit, bool isDumpNativeStack= false)

Note: Active reporting of error info

ParameterTypeNote
typeintException type, C#: 4, js: 5, lua: 6
nameconst char *Exception Name
reasonconst char *Exception Info
stackTraceconst char *Stack
extrasconst char *Other Info
quitboolWhether to quit
isDumpNativeStackboolwhether to dump the Native stack of the current thread

View page: extras: Crash Details->Download Attachments->extraMessage.txt

Native stack: Crash Details->Download Attachments->trace.zip

public static void ReportExceptionJson(int type, const char *exceptionName, const char *exceptionMsg, const char *exceptionStack, const char *paramsJson, bool isDumpNativeStack =false)

Note: Active reporting of error info

ParameterTypeNote
typeintException type, C#: 4, js: 5, lua: 6
exceptionNameconst char *Exception Name
exceptionMsgconst char *Exception Info
exceptionStackconst char *Stack
paramsJsonconst char *Other Info, Json string of map code
quitboolWhether to quit
isDumpNativeStackboolwhether to dump the Native stack of the current thread

View page:

paramsJson: Crash Details->Download Attachments->extraMessage.txt

Native stack: Crash Details->Download Attachments->trace.zip

Other: time used to report the error

AndroidiOS
Attachment sizeDump stackDo not dump stackDump stackDo not dump stack
100K[0.498881]s[0.003127]s[0.117762]s[0.001172]s
10K[0.464859]s[0.000730]s[0.115362]s[0.000445]s
1K[0.477934]s[0.000189]s[0.117078]s[0.000293]s

3.9 Set User ID

public static void SetUserId (const char *userId)
ParameterTypeNote
userIdconst char *User ID

3.10 Mark a Scene

public static void SetScene (int sceneId)
ParameterTypeNote
sceneIdintScene ID

3.11 Set App Version

static void SetAppVersion(const char *appVersion)

Note: Set app version number

For Android, the versionName property of AndroidManifest.xml file is used by default

For iOS, configure Info.plist, {CFBundleShortVersionString}.{CFBundleVersion} into the app version number.

Note: Call it before the InitWithAppId interface.

ParameterTypeNote
appVersionconst char *Version Number

3.12 Add Custom Data

public static void AddSceneData (const char *key, const char *value)

Note: Set the Key-Value data customized by the user. It will be reported together with exception info when sending the crash. Each key shouldn't exceed 100 characters, each value shouldn't exceed 1000 characters, and the total length (all keys+all values) shouldn't exceed 64KB for Android, 128KB for iOS. Supports use in callbacks.

View page: Crash Details->Download Attachments->valueMapOthers.txt

ParameterTypeNote
keyconst char *Key
valueconst char *Value

3.13 Custom Log

public static void PrintLog (LogSeverity level, const char * format, ...)

Note: The custom log shouldn't exceed 30KB.

ParameterTypeNote
levelLogSeverityLog level
formatconst char *Log format

3.14 Set Callback

public static void SetCrashObserver(UQMCrashObserver *crashObserver)

Note: The callback function is called when a crash is detected. Customize the CSCrashCallBack class, inherit UQMCrashObserver, and implement the OnCrashExtraMessageNotify, OnCrashExtraDataNotify methods

ParameterTypeNote
crashObserverUQMCrashObserverUQMCrashObserver Integration

Example:

CSCrashCallBacks.h

// Fill out your copyright notice in the Description page of Project Settings.

#pragma once

#include "CoreMinimal.h"
#include "UQMCrash.h"

/**
 * 
 */
using namespace UQM;

class CRASHSIGHTDEMO_UE_API CSCrashCallBacks : public UQMCrashObserver
{
public:
CSCrashCallBacks();
~CSCrashCallBacks();

const char* OnCrashExtraMessageNotify(int crashType);

long OnCrashExtraDataNotify(const InnerCrashRet &crashRet);
};

CSCrashCallBacks.cpp

#include "CSCrashCallBacks.h"

CSCrashCallBacks::CSCrashCallBacks()
{
}

CSCrashCallBacks::~CSCrashCallBacks()
{
}

const char* CSCrashCallBacks::OnCrashExtraMessageNotify(int crashType) {
char str1[] = "this is extra message.";
char *retValue = SAFE_MALLOC(strlen(str1) + 1, char); // 128*1024 characters at most. The exceeding part will be discarded
strcpy(retValue, str1);
return retValue;
}

long CSCrashCallBacks::OnCrashExtraDataNotify(const InnerCrashRet &crashRet) {
char str[] = "this is extra data.";
strcpy(crashRet.data, str); // Already assigned 128*1024 bytes of storage. No need to assign more. The exceeding part will be discarded
return strlen(str);
}

OnCrashExtraMessageNotify's returned content for Android is on the "Crash Analysis-Trace Data-extraMessage.txt" page. OnCrashExtraDataNotify's returned content for Android is on the "Crash Analysis-Trace Data-userExtraByteData" page, Base64 code OnCrashExtraMessageNotify's returned content for iOS is on the "Crash Analysis-Trace Data-crash_attach.log" page. For iOS, the OnCrashExtraDataNotify interface isn't called

callback type comparison table:

callback typeexception type
0Java crash
2Native crash
3c# exception
4ANR
5JS exception
6lua exception
8custom error

3.15 Set Log Uploading Path

public static void SetLogPath(const char *logPath)

Note: Set an upload path for log after a crash. Read permission is required

ParameterTypeNote
logPathconst char *Log absolute path

3.16 Set Log Uploading Callback

View page: Crash Details-Attachments

public static void SetCrashLogObserver(UQMCrashLogObserver *crashObserver)

Note: The callback function is called when uploading logs. Customize the MyCrashLogCallback class, inherit UQMCrashLogObserver, and implement the OnCrashSetLogPathNotify, OnCrashLogUploadResultNotify methods

ParameterTypeNote
crashObserverUQMCrashLogObserverSubclass of UQMCrashLogObserver

Example:

MyCrashLogCallback.h

// Fill out your copyright notice in the Description page of Project Settings.

#pragma once

#include "CoreMinimal.h"
#include "UQMCrash.h"

using namespace UQM;
/**
*
*/
class UQMCRASHSIGHTTEST_API MyCrashLogCallback: public UQMCrashLogObserver
{
public:
MyCrashLogCallback();
~MyCrashLogCallback();

// Set log path callback
const char* OnCrashSetLogPathNotify(int crashType);

// Callback for notifying the log uploading results
void OnCrashLogUploadResultNotify(int crashType, int result);
};

MyCrashLogCallback.cpp

// Fill out your copyright notice in the Description page of Project Settings.

#include "MyCrashLogCallback.h"

MyCrashLogCallback::MyCrashLogCallback()
{
}

MyCrashLogCallback::~MyCrashLogCallback()
{
}

// Set log path callback
// @param crashType Crash type, 0: Java crash, 2: Native crash
// @result Absolute path of log. If non-empty, it overwrites the path of SetCrashLogObserver interface
const char *MyCrashLogCallback::OnCrashSetLogPathNotify(int crashType)
{
const char *path = "/data/data/packagename/app_crashSight/log.txt";
return path;
}

// Callback for notifying the log uploading results
// @param crashType Crash type, 0: Java crash, 2: Native crash
// @param retust Log uploading result, 0: successful, other: failed
void MyCrashLogCallback::OnCrashLogUploadResultNotify(int crashType, int result)
{
}

3.17 Set Android Logcat Size

public static void SetLogcatBufferSize(int size)

Note: Set the size of logcat logs uploaded on crashes and errors, valid only for Android. It is recommended to set it less than 128KB. The default value is 30KB.

ParameterTypeNote
sizeintLogcat log size in bytes

4.Interfaces (Windows)

4.1 Initialization

static int  InitContext(const char *user_id, const char *version, const char *key);

Note: Performs initialization. Perform initialization at the earliest possible location to enable crash capture and reporting.

ParameterTypeNote
userIdstringUser Id
versionstringVersion
keystringAPP key of registered project

4.2 Proactive Exception Reporting

static void ReportException(int type, const char *exp_name, const char *exp_message, const char *stack_trace, const char *extras, bool is_async, const char *error_attach_path);

Note:Report an Exception

ParameterTypeNote
typeintexception type, C#: 4, js: 5, lua: 6
exp_nameconst char *exception name
exp_messageconst char *exception message
stack_traceconst char *exception stack
extrasconst char *extra information
is_asyncboolAsynchronous or not
error_attach_pathconst char *Absolute path of the attachment (GBK characters are not supported)
static void ReportExceptionW(int type, const char *exp_name, const char *exp_message, const char *stack_trace, const char *extras, bool is_async, const wchar_t *error_attach_path);

Note:Report an Exception

ParameterTypeNote
typeintexception type, C#: 4, js: 5, lua: 6
exp_nameconst char *exception name
exp_messageconst char *exception message
stack_traceconst char *exception stack
extrasconst char *extra information
is_asyncboolAsynchronous or not
error_attach_pathconst wchar_t *Absolute path of the attachment

4.3 Add Custom Data

static void SetUserValue(const char *key, const char *value);

Note: Set user-defined Key-Value data, which will be reported with the exception message when sending Crash, the length of a single key is limited to 100 characters, and the length of a single value is limited to 1000 characters.

View in webpage: Crash detail page -> Value Map

ParameterTypeNote
keyconst char *key
valueconst char *value

4.4 Set Custom Log Path

static void SetCustomLogDir(const char *log_path);

View in webpage: Crash detail page -> Attachments -> CustomizedLogFile.zip

ParameterTypeNote
log_pathconst char *log path (GBK characters are not supported)
static void SetCustomLogDirW(const wchar_t *log_path);

View in webpage: Crash detail page -> Attachments -> CustomizedLogFile.zip

ParameterTypeNote
log_pathconst char *log path

When you need to pass in a path with Unicode characters, use the wide character version (SetCustomLogDirW)
When you need to upload multiple logs, please use "|" to separate the paths, and pass in the absolute paths of up to 3 files at a time, directories are not supported. The maximum support for a single file is 20MB, the file size over 20MB will intercept the last 20MB; the maximum support for compressed package is 10MB, the files will be put into the compressed package in order, if the compressed package size would be more than 10MB when a file is put in, the file will be skipped.

4.5 Set User ID

static void SetUserId(const char *user_id);

Note: Set user ID. Please call it after initialization.

ParameterTypeNote
user_idconst char *User ID

4.6 Add Custom Log

static void PrintLog(LogSeverity level, const char *tag, const char *format, ...);

Note: Customized log with a limit of 30KB. Android does not support writing custom logs in crash callbacks.

ParameterTypeNote
levelCSLogSeveritylog level
tagconst char *log tag
formatconst char *log format
argsparams object[]variable arguments

4.7 Enable Veh Exception Handling

static void SetVehEnable(bool enable);
ParameterTypeNote
enableboolVeh Exception Handler Switch

4.8 Proactive Crash Reporting

static void ReportCrash();

Note: Report a Crash.

4.9 Proactive Dump Reporting

static void ReportDump(const char *dump_path, bool is_async);
ParameterTypeNote
dump_pathconst char *dump path
is_asyncboolAsynchronous or not

4.10 Setting Crash Callbacks

static void SetCrashCallback(CrashCallbackFuncPtr callback);
ParameterTypeNote
callbackCrashCallbackFuncPtrCrash callback function pointer

The callback function is defined as:

typedef void (*CrashCallbackFuncPtr)(int type, const char *guid);
ParameterTypeNote
typeintCrash Type
guidconst char *Client Report ID

4.11 Enable Additional Exception Handling

static void SetExtraHandler(bool extra_handle_enable);

Note: Set additional exception handling mechanism, default is off, consistent with old version. When turned on, it can catch crashes caused by illegal arguments thrown by safe functions such as strcpy_s, as well as crashes caused by purecall errors in dummy function calls.

ParameterTypeNote
extra_handle_enableboolAdditional Exception Handler Switch

4.12 Upload Dump File

static void UploadGivenPathDump(const char *dump_dir, bool is_extra_check);

Note: Upload the dump file in the specified path.

ParameterTypeNote
dump_dirconst char *Dump file path
is_extra_checkboolJust fill in false by default

4.13 UE Critical Error Reporting

static void UnrealCriticalErrorEnable(bool enable);

Note: Set whether to report UE's Critical Error.

ParameterTypeNote
enableboolUE Critical Error Reporting Switch

4.14 Enable Report Only the First Crash

static void OnlyUploadFirstCrash(bool enable);

Note: When turned on, only the first captured crash will be reported per startup, preventing duplicate reports. Effective only when VEH Capture is turned off

ParameterTypeNote
enableboolEnable report only the first crash

4.15 Set Custom Attachment Path

static void SetCustomAttachDir(const char *attach_path);

View in webpage: Crash detail page -> Attachments -> CustomizedAttachFile.zip

ParameterTypeNote
attach_pathconst char *log path (GBK characters are not supported)
static void SetCustomAttachDirW(const wchar_t *attach_path);

View in webpage: Crash detail page -> Attachments -> CustomizedAttachFile.zip

ParameterTypeNote
attach_pathconst char *log path

When you need to pass in a path with Unicode characters, use the wide character version (SetCustomAttachDirW)
When you need to upload multiple attachments, please use "|" to separate the paths, and pass in the absolute paths of up to 3 files at a time, directories are not supported. The maximum support for a single file is 20MB, the file size over 20MB will be skipped; the maximum support for compressed package is 10MB, the files will be put into the compressed package in order, if the compressed package size would be more than 10MB when a file is put in, the file will be skipped.

5.Android Additional Operations

5.1 Enable Critical Error reporting

On the Android platform, the Unreal engine sets the exit method for Critical Error to Normal Exit, making it not possible for CrashSight to capture this type of crash directly. In order to catch Critical Error, you need to find the UE engine code at the following location:

change

FPlatformMisc::RequestExit(true);

to

abort();

Critical Error for iOS exits with a crash, so no changes are needed.

5.2 Fix unwind issue in UE5.1 and later

Android projects packaged with Unreal engine 5.1 and later suffer from unwind crashes, causing native crash reporting to fail. Here is how to avoid the unwind crash issue by modifying the source code in Unreal Engine:

6.Integration Result Testing

CrashSight Test Interface

Test Java crash (Android)

static void TestJavaCrash();

Test Object-C crash (iOS)

static void TestOcCrash();

Test Native crash (Android&iOS)

static void TestNativeCrash();

6.1. Testing Method for iOS:

  • a. Enable Debug mode. Initialize CrashSight and assign suitable config parameters
  • b. Network and report: Check if "begin to upload <CSAnalyticsLogic" or "cmd: 641" is printed in the test device log
  • c. Crash detection: Check if "Handle the crash scene in callback" is printed in the test device log
  • d. Report exceptions: Check if "begin to upload <CSCrashLogic" or "cmd: 631" is printed in the test device log

6.2. Testing Method for Android:

  • a. Enable Debug mode. Initialize CrashSight and assign suitable config parameters
  • b. Network and report: Check if "[Upload] Run upload task with cmd: 840" is printed in the logcat log.
  • c. Crash detection: Check if "HandleSignal start" is printed in the logcat log
  • d. Report exception: Check if "[Upload] Run upload task with cmd: 830" is printed in the logcat log.

6.3. Testing Method for Windows:

  • a.Verify if CrashSight can connect to the internet and report normally. The verification process is:

    1. Initialize CrashSight;
    2. Wait 5 minutes and go to Exception Overview --> Crash Tendency --> Number of Devices Connected in the management console. The stats should be equal to or higher than 1.
  • b.Verify if a crash can be reported normally. The verification process is:

    1. Initialize CrashSight;
    2. You can trigger a crash in the game using the following code. (You can also use other bad memory access methods)
    int* a = NULL;
    a[10000] = 5;
  • c.See if there is a generated dmp file under CrashSight64/dump(TQM64/dump for older versions) path. The crash is not successfully captured if you are unable to find the file. In this case, please contact CrashSight developer.

  • d.Go to "Crash Analysis" in the management console and see if there is a report with the corresponding time stamp. If you see the dmp file in step 3 but are unable to find the report in step 4, the crash was not successfully reported. Please check APPID config (Both config files need to be correct) and the APP KEY config if they correspond to each other and are the same in the application config. If it still fails to report using the correct config, please contact CrashSight developers.

  • e.Check if the version number and the user name of the crash report is the same as the configuration.

  • f.Check if the version number and the user name of the error report is the same as the configuration.

7.Upload Symbol Table

The above is an introduction to SDK Integration, crash reporting and verifying, but to see readable symbolicated stacks on the page, you need to upload the corresponding symbol table. Please seeSymbol Table Uploading Tools Guide