Unreal Integration Guidelines
This document applies to CrashSight SDK 4.3.x version. For 4.2.x version, please refer to old 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
- 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
using namespace GCloud::CrashSight;
#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:
- Android: https://android.crashsight.qq.com/pb/async
- iOS: https://ios.crashsight.qq.com/pb/sync
- Windows: pc.crashsight.qq.com
- Mac: https://mac.crashsight.qq.com/pb/sync
International public cloud:
- Android: https://android.crashsight.wetest.net/pb/async
- iOS: https://ios.crashsight.wetest.net/pb/sync
- Windows: pc.crashsight.wetest.net
- Mac: https://mac.crashsight.wetest.net/pb/sync
1.3.1 Windows configuration
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.1.1, which will provide more accurate crash reporting. For other users using the official engine version, use the configuration in 1.3.1.2.
1.3.1.1 Solution A
a. Copy CrashSightReporter.h from SDK package (\Plugins\CrashSight\Source\CrashSight\Public\CrashSightReporter.h) into the engine source code \Engine\Source\Runtime\Core\Public\Windows directory.
b. Include 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);
c. Include CrashSightReporter.h into the engine source code \Engine\Source\Runtime\Core\Private\Misc\AssertionMacros.cpp, and in the function EnsureFailed, call FCrashSightReporter::ReportEnsureToCrashSight(ErrorMsg, ANSI_TO_TCHAR(StackTrace));, after the stacktrace is dumped.
d. Compile the engine.
e. After initializing with the function GCloud::CrashSight::CrashSightAgent::InitWithAppId, call GCloud::CrashSight::CrashSightAgent::SetVehEnable(false)
f. Call GCloud::CrashSight::CrashSightAgent::OnlyUploadFirstCrash(true) after GCloud::CrashSight::CrashSightAgent::SetVehEnable(false)
Note: CrashSight64.dll version 2.2.2.929 and above support solution A
1.3.1.2 Solution B
a. Call GCloud::CrashSight::CrashSightAgent::SetVehEnable(true) after initializing with the function GCloud::CrashSight::CrashSightAgent::InitWithAppId
b. Call GCloud::CrashSight::CrashSightAgent::UnrealCriticalErrorEnable(true) after GCloud::CrashSight::CrashSightAgent::SetVehEnable(true)
1.3.2 Mac configuration
If you are prompted that “CrashSight.dylib” cannot be opened when integrating on MacOS, please execute the following command to ensure that CrashSight.dylib passes the MacOS security checksum:
sudo xattr -r -d com.apple.quarantine path/to/CrashSight.dylib
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
Platform-wide interfaces are interfaces that are common to all platforms, they cover most of the basic functions of CrashSight, such as: initialization, error reporting, and so on. In addition, each platform may have some unique interfaces, which will be listed separately later. The total number of interfaces that can be used on a platform is: platform-wide interfaces + interfaces unique to that platform.
3.1 Platform-wide interfaces
3.1.1 Initialization
static void InitWithAppId(const char* app_id);
Note: Execute initialization. Initialize as early as possible to enable crash detection and reporting features. The appid is CrashSight's unique identifier for the item, and can be viewed in Product Settings -> Product Information.
| Parameter | Type | Note |
|---|---|---|
| app_id | const char* | APP ID of registered projects |
3.1.2 Reporting errors
static void ReportException(int type, const char* name, const char* reason, const char* stack_trace, const char* extras, bool quit, int dump_native_type = 0, bool is_async = true, const char *error_attach_path = nullptr);
Note: Proactively report error messages. Can be called manually when an error is caught or needs to be reported, multi-threaded calls are supported. name, reason and stack_trace cannot be null.
| Parameter | Type | Note |
|---|---|---|
| type | int | Exception Type, C#: 4, js: 5, lua: 6 |
| name | const char * | Exception Name |
| reason | const char * | Exception Info |
| stack_trace | const char * | Stack |
| extras | const char * | Other Info |
| quit | bool | Whether to quit |
| dump_native_type | int | 0: close, 1: call system interface dump, 3: minidump (valid for mobile only) |
| is_async | bool | asynchronous (valid for Win, Xbox) |
| error_attach_path | const char * | Absolute path of the attachment (GBK characters are not supported) (valid for Win, Xbox) |
static void ReportExceptionW(int type, const char* name, const char* reason, const char* stack_trace, const char* extras, bool quit, int dump_native_type = 0, bool is_async = true, const wchar_t *error_attach_path);
Note:Report an Exception (Windows only)
| Parameter | Type | Note |
|---|---|---|
| type | int | Exception Type, C#: 4, js: 5, lua: 6 |
| name | const char * | Exception Name |
| reason | const char * | Exception Info |
| stack_trace | const char * | Stack |
| extras | const char * | Other Info |
| quit | bool | Whether to quit |
| dump_native_type | int | 0: close, 1: call system interface dump, 3: minidump (valid for mobile only) |
| is_async | bool | asynchronous (valid for Win, Xbox) |
| error_attach_path | const wchar_t * | Absolute path of the attachment (valid for Win, Xbox) |
View page:
paramsJson: Crash Details->Download Attachments->extraMessage.txt
dump: 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.1.3 Setting user ID
static void SetUserId(const char* user_id);
Note: Setting user ID. The user id defaults to unknown.
| Parameter | Type | Note |
|---|---|---|
| user_id | const char * | User ID |
3.1.4 Adding custom data
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.
View page: Crash Details->Download Attachments->valueMapOthers.txt
| Parameter | Type | Note |
|---|---|---|
| key | const char * | Key |
| value | const char * | Value |
3.1.5 Setting the application version
static void SetAppVersion(const char* app_version);
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.
Not available for Win, Xbox now
Note: Call it before the InitWithAppId interface.
| Parameter | Type | Note |
|---|---|---|
| app_version | const char * | Version Number |
3.1.6 Reporting domain name settings
static void ConfigCrashServerUrl(const char* crash_server_url);
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.
| Parameter | Type | Note |
|---|---|---|
| crash_server_url | const char * | Target domain name of reporting |
3.1.7 Set upload log path
static void SetLogPath(const char* log_path);
Note: Set an upload path for log after a crash. Read permission is required. On Android and iOS, this interface has a lower priority than logpath callback. Attachment paths with GBK characters are not supported on Windows. Not available for Switch, and not available for Harmony at this time
| Parameter | Type | Note |
|---|---|---|
| log_path | const char * | Log absolute path |
static void SetLogPathW(const wchar_t* log_path);
Note: Set an upload path for log after a crash. Read permission is required. Available for Windows only, supports attachment paths with GBK characters.
| 参数 | 类型 | 说明 |
|---|---|---|
| log_path | const wchar_t * | Log absolute path |
3.1.8 Enable Debug
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. Not available for Win、Xbox、Linux
Note: Call it before the InitWithAppId interface.
| Parameter | Type | Note |
|---|---|---|
| enable | bool | Enabling switch for debugging |
3.1.9 Set device id
static void SetDeviceId(const char* device_id);
Note: Set the device ID, by default uuid is used as the device ID Not available for Win、Xbox、PS4、PS5、Switch、Harmony
Note: Call it before the InitWithAppId interface.
| Parameter | Type | Note |
|---|---|---|
| device_id | const char * | Device ID |
3.1.10 Set custom log reporting level
static void ConfigCrashReporter(int log_level);
Note: Set custom log reporting level. Off=0, Error=1, Warn=2, Info=3, Debug=4, default is Info.
Note: Call it before the InitWithAppId interface.
| Parameter | Type | Note |
|---|---|---|
| log_level | int | Log level |
3.1.11 Customize logging
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 |
| args | params object[] | variable arguments |
static void PrintLog(LogSeverity level, const char* tag, const char* format, ...);
Note: Customized log with a limit of 30KB Not available for Android、iOS、Linux
| Parameter | Type | Note |
|---|---|---|
| level | CSLogSeverity | log level |
| tag | const char * | log tag |
| format | const char * | log format |
| args | params object[] | variable arguments |
Custom log view: Android, iOS, PS4, PS5, Switch: issue details->tracking log->custom log Windows, Xbox, Linux: issue details -> custom log (from interface)
3.2 Android, iOS, Mac interfaces
3.2.1 Callback switches
static void ConfigCallbackType(int32_t callback_type);
Note: The callback switches for each type of reporting are currently 5 types of Type, represented by 5 bits. The first bit indicates crash, the second bit indicates anr, the third bit indicates u3d c# error, the fourth bit indicates js, and the fifth bit indicates lua, defaults to full on.
| Parameter | Type | Note |
|---|---|---|
| callback_type | int32_t | callback switch |
3.2.2 Setting Android phone model
static void SetDeviceModel(const char* device_model);
Note: Set phone model
Note: Call it before the InitWithAppId interface.
| Parameter | Type | Note |
|---|---|---|
| device_model | const char * | Phone model |
3.2.3 Report an error
static void ReportExceptionJson(int type, const char* exception_name, const char* exception_msg, const char* exception_stack, const char* params_json, int dump_native_type = 0, const char* errorAttachmentPath = "");
Note: Active reporting of error info, other information must be a Json string, an attachment can be specified to be uploaded.
| Parameter | Type | Note |
|---|---|---|
| type | int | Exception Type, C#: 4, js: 5, lua: 6 |
| exception_name | const char * | Exception Name |
| exception_msg | const char * | Exception Info |
| exception_stack | const char * | Stack |
| params_json | const char * | Other Info, Json string of map code |
| dump_native_type | int | 0: close, 1: call system interface dump, 3: minidump |
| errorAttachmentPath | const char * | Absolute path of the attachment |
View page:
paramsJson: Crash Details->Download Attachments->extraMessage.txt
Native stack: Crash Details->Download Attachments->trace.zip
3.2.4 Reporting lightweight logs
static void ReportLogInfo(const char* msg_type, const char* msg);
Note: Reporting lightweight logs
| Parameter | Type | Note |
|---|---|---|
| msg_type | const char * | log Type |
| msg | const char * | log message |
3.2.5 Tagging scenes
static void SetScene(int scene_id);
Note: Set scene id.
| Parameter | Type | Note |
|---|---|---|
| scene_id | int | scene ID |
3.2.6 Enable multi-signal capture
static void SetCatchMultiSignal(bool enable);
Note: Capture multiple signals from different threads and upload information about the first signal, which is turned off by default.
| Parameter | Type | Note |
|---|---|---|
| enable | bool | Multi-Signal Capture Switch |
3.2.7 Enable report last frame
static void SetUnwindExtraStack(bool enable);
Note: Goes back up to 256 frames and reports the last frame even if the stack string is full, which is turned off by default.
| Parameter | Type | Note |
|---|---|---|
| enable | bool | Report last frame switch |
3.2.8 Get crash thread ID
static long GetCrashThreadId();
Note: When a crash occurs, get the crash thread ID and return -1 on failure, can be called in a callback
3.2.9 Set custom device ID
static void SetCustomizedDeviceID(const char* device_id);
Note: Setting a custom device ID
| Parameter | Type | Note |
|---|---|---|
| device_id | const char* | custom device ID |
3.2.10 Get SDK-generated device ID
static void GetSDKDefinedDeviceID(void* data, int len);
Note: Get the device ID generated by the SDK
| Parameter | Type | Note |
|---|---|---|
| data | void* | Points to the memory used to hold the device ID |
| len | int | Length of data |
3.2.11 Set custom match ID
static void SetCustomizedMatchID(const char* match_id);
Note: Setting a custom match ID. The match id can be used to find crashes and errors in Advanced Search.
| Parameter | Type | Note |
|---|---|---|
| match_id | const char* | match ID |
3.2.12 Get SDK-generated session ID
static void GetSDKSessionID(void* data, int len);
Note: Get the session ID generated by the SDK. The session ID is used to uniquely mark a startup and is generally used in callbacks to determine if it is the same startup.
| Parameter | Type | Note |
|---|---|---|
| data | void* | Points to the memory used to hold the session ID |
| len | int | Length of data |
3.2.13 Get if last time was crash exit
static bool IsLastSessionCrash();
Note: Whether the last time was a crash exit, generally used in callbacks.
3.2.14 Get last user ID
static void GetLastSessionUserId(void* data, int len);
Note: Typically used with IsLastSessionCrash to get the last user ID in a callback
| Parameter | Type | Note |
|---|---|---|
| data | void* | Points to the memory used to hold the user ID |
| len | int | Length of data |
3.2.15 Set report thread count
static void SetUploadThreadNum(int num);
Note: Setting the number of reporting threads. The default is 3.
| Parameter | Type | Note |
|---|---|---|
| num | int | Set the number of reporting threads, default is 3 |
3.2.16 Set game type
static void SetGameType(int game_type);
Note: Set the game Type, Cocos=1, Unity=2, UE4=3, UE5=4
| Parameter | Type | Note |
|---|---|---|
| game_type | int | game Type |
3.2.17 Get crash UUID
static void GetCrashUuid(void* data, int len);
Note: Get the UUID of the current report, the UUID is used to uniquely identify a report, usually used in callbacks.
| Parameter | Type | Note |
|---|---|---|
| data | void* | Points to the memory used to hold the crash UUID |
| len | int | Length of data |
3.2.18 Set logcat buffer size
static void SetLogcatBufferSize(int size);
Note: Set logcat buffer size, default 10KB in non-debug mode, 128KB in debug mode
| Parameter | Type | Note |
|---|---|---|
| size | int | logcat buffer size |
3.2.19 Start timed dump
static void StartDumpRoutine(int dumpMode, int startTimeMode, long startTime, long dumpInterval, int dumpTimes, bool saveLocal, const char *savePath);
Note: Start a thread to fetch the dump and report it at regular intervals. Depending on the settings of dump interval and number of dumps, there will be some performance overhead, generally used for testing. Please disable this feature before official release.
| Parameter | Type | Note |
|---|---|---|
| dumpMode | int | dump mode, 1: dump, 2: minidump |
| startTimeMode | int | Start time mode, 0: absolute time, 1: relative time, unit: milliseconds |
| startTime | long | start time |
| dumpInterval | long | Dump interval in milliseconds |
| dumpTimes | int | Number of dumps |
| saveLocal | bool | Whether to save local |
| savePath | const char * | Local Save Path |
3.2.20 Get exception type number
static int GetExceptionType(const char *name);
Note: Get the exception type number based on the string of the exception name, which can be used to fill in the type parameter of the ReportException interface
| Parameter | Type | Note |
|---|---|---|
| name | const char * | Exception Type name, e.g. "c#", "js", "lua", "custom1", etc. |
3.2.21 Setting callbacks
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(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 type | exception type |
|---|---|
| 0 | Java crash |
| 2 | Native crash |
| 3 | c# exception |
| 4 | ANR |
| 5 | JS exception |
| 6 | lua exception |
| 8 | custom error |
3.2.22 Set log upload 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.3 PC, Xbox interfaces
3.3.1 Enable Veh exception handling
static void SetVehEnable(bool enable);
Note: VEH capture switch, on by default. It is recommended that all Unreal projects turn this switch on (no need to call it), otherwise it may generate crash misses.
| Parameter | Type | Note |
|---|---|---|
| enable | bool | Veh Exception Handler Switch |
3.3.2 Proactive crash reporting
static void ReportCrash();
Note: Report a Crash. There are generally no usage scenarios, and can be used at your discretion depending on the needs of your project.
3.3.3 Proactive Dump Reporting
static void ReportDump(const char *dump_path, bool is_async);
Note: Active Dump reporting. generally no use scenarios, can be used as appropriate according to the needs of the project.
| Parameter | Type | Note |
|---|---|---|
| dump_path | const char * | dump path |
| is_async | bool | Asynchronous or not |
3.3.4 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 | 崩溃的Type |
| guid | const char * | Client Report ID |
3.3.5 Enable additional exception catching
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 |
3.3.6 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 |
3.3.7 UE Critical Error upload
static void UnrealCriticalErrorEnable(bool enable);
Note: Set whether to report UE's Critical Error, the default is on. Unreal projects please turn it on. Android projects also need to Enable Critical Error reporting
| Parameter | Type | Note |
|---|---|---|
| enable | bool | UE Critical Error Reporting Switch |
3.3.8 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
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | Enable report only the first crash |
3.4 PS4, PS5, Switch interfaces
3.4.1 Setting the error reporting interval
static void SetErrorUploadInterval(int interval);
Note: Setting the error reporting interval, the default is 30s.
| Parameter | Type | Note |
|---|---|---|
| interval | int | Error Reporting Interval |
3.4.2 Error Reporting Switch
static void SetErrorUploadEnable(bool enable);
Note: Whether to enable error reporting, the default is on.
| Parameter | Type | Note |
|---|---|---|
| enable | bool | Error Reporting Switch |
3.5 Linux interfaces
3.5.1 Set path to all log files
static void SetRecordFileDir(const char* record_dir);
Note: Set the path to all log files, including SDK logs and dump files, defaults to the directory of the current executable.
| Parameter | Type | Note |
|---|---|---|
| record_dir | const char* | Record file path |
4.Android Additional Operations
4.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.
4.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:
4.3 Configuring native library extraction
Unextracted native libraries may cause crash stack cannot be symbolicated. This is manifested by the fact that the crash module in the stack is xx.apk instead of xx.so and cannot be localized to a specific library.
In order to avoid the impact of unextracted native libraries on the stack symbolication, please do the following configuration:
Locate the DefaultEngine.ini file in the Config directory of the UE project, add
bExtractNativeLibs=True
to the
[/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]
section.
By adding this parameter, the operating system can provide additional information in the event of an application crash to help analyze the cause of the crash.
5.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, will support all platforms in the future)
static void TestNativeCrash();
Test OOM crash（Android、iOS）
static void TestOomCrash();
Test ANR (Android)
static void TestANR();
Test for using memory after release, only effective when GWP_Asan or MTE function is enabled (Android)
static void TestUseAfterFree();
5.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
5.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.
5.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 = 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.
6.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