- 1 Integration in Unreal
- 2 Integration in System Native Layer
- 3 Interfaces
- 4.Interfaces (Windows)
- 5.Android Additional Operations
- 6.Integration Result Testing
- 7.Upload Symbol Table
Unreal SDK Integration
This document applies to the current stable version, Android, iOS and Windows platforms can refer to this document to integrate. Xbox, PS4, PS5, Switch and Linux platforms can refer to the new version of Unreal SDK Integration Document
1 Integration in Unreal
1.1 Import CrashSight UE Plugin
- 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:
- 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.
- 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
Domestic public cloud:
- Android: https://android.crashsight.qq.com/pb/async
- iOS: https://ios.crashsight.qq.com/pb/sync
Overseas public cloud:
- Android: https://android.crashsight.wetest.net/pb/async
- iOS: https://ios.crashsight.wetest.net/pb/sync
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
- Copy CrashSightReporter.h into the engine source code \Engine\Source\Runtime\Core\Public\Windows directory
- 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);
- Compile the engine
- After initializing with the function CrashSight::CrashSightBridge::InitContext, call CrashSight::CrashSightBridge::SetVehEnable(false)
1.3.2.2 Solution B
- Call CrashSight::CrashSightBridge::SetVehEnable(true) after initializing with the function CrashSight::CrashSightBridge::InitContext
- Call CrashSight::CrashSightBridge::UnrealCriticalErrorEnable(true) after CrashSight::CrashSightBridge::SetVehEnable(true)
After the project is packaged, create a TQM64/dump directory and GameBabyConfig64.dat file in the same level directory as CrashSight64.dll. There are three parameters to be updated in the GameBabyConfig64.dat file:
1)GameName
2)Reported URL
3)APPID
<GameBabyConfig __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.qq.com</DomainUrl>
</GameBabyConfig>
2 Integration in System Native Layer
Due to the late timing of initializing and completing the registration of the signal processing function after the engine is started, resulting in previous crashes that cannot be captured, it is necessary to initialize and complete the signal registration in advance in the following way.
Execute 1.1 and 1.2 of Integration in Unreal. Then initialize CrashSight in the native layer. The initialization reference code is as follows:
Android:
import com.uqm.crashsight.core.api.crash.UQMCrash;
...
//Fill in the configuration information first, this is only an example
System.loadLibrary("CrashSight");
UQMCrash.configDebugModeBeforeInit(true);//Enable debug
UQMCrash.setUserId("testUserId");//Set user ID
UQMCrash.setAppVersion("testVersion");//Set app version
//Then initialize CrashSight
UQMCrash.configCrashServerUrlBeforeInit("https://android.crashsight.wetest.net/pb/async");
UQMCrash.initWithAppId("******");
iOS:
#include "CrashSight/CrashSightCore.framework/Headers/CrashSightAgent.h"
...
//Fill in the configuration information first, this is only an example, specific configuration interfaces can be found in CrashSightAgent.h
GCloud::CrashSight::CrashSightAgent::ConfigDebugMode(true);//Enable debug
GCloud::CrashSight::CrashSightAgent::SetUserId("testUserId");//Set user ID
GCloud::CrashSight::CrashSightAgent::SetAppVersion("testVersion");//Set app version
//Then initialize CrashSight
GCloud::CrashSight::CrashSightAgent::ConfigCrashServerUrl("https://ios.crashsight.wetest.net/pb/sync");
GCloud::CrashSight::CrashSightAgent::InitWithAppId("******");
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.
Parameter | Type | Note |
---|---|---|
appId | string | APP 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.
Parameter | Type | Note |
---|---|---|
enable | bool | Enabling 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 domestic public environment is as follows:
- Android: https://android.crashsight.qq.com/pb/async
- iOS: https://ios.crashsight.qq.com/pb/sync
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.
Parameter | Type | Note |
---|---|---|
crashServerUrl | const 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.
Parameter | Type | Note |
---|---|---|
logLevel | int | Log 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.
Parameter | Type | Note |
---|---|---|
channel | const char * | Channel |
version | const char * | App Version |
user | const char * | User ID |
delay | long | Delay(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.
Parameter | Type | Note |
---|---|---|
deviceId | const 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.
Parameter | Type | Note |
---|---|---|
deviceModel | const 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
Parameter | Type | Note |
---|---|---|
type | int | Exception type, C#: 4, js: 5, lua: 6 |
name | const char * | Exception Name |
reason | const char * | Exception Info |
stackTrace | const char * | Stack |
extras | const char * | Other Info |
quit | bool | Whether to quit |
isDumpNativeStack | bool | whether 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
Parameter | Type | Note |
---|---|---|
type | int | Exception type, C#: 4, js: 5, lua: 6 |
exceptionName | const char * | Exception Name |
exceptionMsg | const char * | Exception Info |
exceptionStack | const char * | Stack |
paramsJson | const char * | Other Info, Json string of map code |
quit | bool | Whether to quit |
isDumpNativeStack | bool | whether 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
Android | iOS | |||
---|---|---|---|---|
Attachment size | Dump stack | Do not dump stack | Dump stack | Do 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)
Parameter | Type | Note |
---|---|---|
userId | const char * | User ID |
3.10 Mark a Scene
public static void SetScene (int sceneId)
Parameter | Type | Note |
---|---|---|
sceneId | int | Scene 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.
Parameter | Type | Note |
---|---|---|
appVersion | const 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
Parameter | Type | Note |
---|---|---|
key | const char * | Key |
value | const char * | Value |
3.13 Custom Log
public static void PrintLog (LogSeverity level, const char * format, ...)
Note: The custom log shouldn't exceed 30KB.
Parameter | Type | Note |
---|---|---|
level | LogSeverity | Log level |
format | const 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
Parameter | Type | Note |
---|---|---|
crashObserver | UQMCrashObserver | UQMCrashObserver 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();
long OnCrashExtraDataNotify(const InnerCrashRet &crashRet);
};
CSCrashCallBacks.cpp
#include "CSCrashCallBacks.h"
CSCrashCallBacks::CSCrashCallBacks()
{
}
CSCrashCallBacks::~CSCrashCallBacks()
{
}
const char* CSCrashCallBacks::OnCrashExtraMessageNotify() {
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
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
Parameter | Type | Note |
---|---|---|
logPath | const char * | Log absolute path |
3.16 Set Log Uploading Callback
View page: Crash Details-Trace Data-Client Reporting Log
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
Parameter | Type | Note |
---|---|---|
crashObserver | UQMCrashLogObserver | Subclass 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.
Parameter | Type | Note |
---|---|---|
size | int | Logcat 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.
Parameter | Type | Note |
---|---|---|
userId | string | User Id |
version | string | Version |
key | string | APP 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
Parameter | Type | Note |
---|---|---|
type | int | exception type, C#: 4, js: 5, lua: 6 |
exp_name | const char * | exception name |
exp_message | const char * | exception message |
stack_trace | const char * | exception stack |
extras | const char * | extra information |
is_async | bool | Asynchronous or not |
error_attach_path | const 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
Parameter | Type | Note |
---|---|---|
type | int | exception type, C#: 4, js: 5, lua: 6 |
exp_name | const char * | exception name |
exp_message | const char * | exception message |
stack_trace | const char * | exception stack |
extras | const char * | extra information |
is_async | bool | Asynchronous or not |
error_attach_path | const 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
Parameter | Type | Note |
---|---|---|
key | const char * | key |
value | const char * | value |
4.4 Set Custom Log Path
static void SetCustomLogDir(const char *log_path);
View in webpage: Crash detail page -> Custom Log (via File)
Parameter | Type | Note |
---|---|---|
log_path | const char * | log path (GBK characters are not supported) |
static void SetCustomLogDirW(const wchar_t *log_path);
View in webpage: Crash detail page -> Custom Log (via File)
Parameter | Type | Note |
---|---|---|
log_path | const char * | log path |
4.5 Set User ID
static void SetUserId(const char *user_id);
Note: Set user ID. Please call it after initialization.
Parameter | Type | Note |
---|---|---|
user_id | const 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.
Parameter | Type | Note |
---|---|---|
level | CSLogSeverity | log level |
tag | const char * | log tag |
format | const char * | log format |
args | params object[] | variable arguments |
4.7 Enable Veh Exception Handling
static void SetVehEnable(bool enable);
Parameter | Type | Note |
---|---|---|
enable | bool | Veh 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);
Parameter | Type | Note |
---|---|---|
dump_path | const char * | dump path |
is_async | bool | Asynchronous or not |
4.10 Setting Crash Callbacks
static void SetCrashCallback(CrashCallbackFuncPtr callback);
Parameter | Type | Note |
---|---|---|
callback | CrashCallbackFuncPtr | Crash callback function pointer |
The callback function is defined as:
typedef void (*CrashCallbackFuncPtr)(int type, const char *guid);
Parameter | Type | Note |
---|---|---|
type | int | Crash Type |
guid | const 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.
Parameter | Type | Note |
---|---|---|
extra_handle_enable | bool | Additional 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.
Parameter | Type | Note |
---|---|---|
dump_dir | const char * | Dump file path |
is_extra_check | bool | Just 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.
Parameter | Type | Note |
---|---|---|
enable | bool | UE 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
Parameter | Type | Note |
---|---|---|
enable | bool | Enable report only the first crash |
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. If possible, please upgrade the engine to a newer version as soon as possible to completely eliminate this issue. 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:
- Initialize CrashSight;
- 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:
- Initialize CrashSight;
- You can trigger a crash in the game using the following code. (You can also use other bad memory access methods)
int* a = 0; a[10000] = 5;
c.See if there is a generated dmp file under TQM64/dump. 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 restored stacks on the page, you need to upload the corresponding symbol table. Please seeSymbol Table Uploading Tools Guide