Unreal SDK Integration

1 Integration in Unreal

1.1 Import CrashSight UE4 Plugin

• 1. Download CrashSighUnrealPlugin (Download is unavailable due to an ongoing internal review. To download it, please contact WeTest@wetest.net)
• 2. Unpack Plugins files under the same directory. Copy the CrashSight directory in the Plugins folder to the Plugins directory under the UE4 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.
     
• 3. Compile CrashSight plugin source code and project source code together. When done, you can see the CrashSight plugin on the plugin editing page of UE4 editor, as shown in the image.
     

1.2 Configure Permissions

• Permission configuration

Change permission settings in the AndroidManifest.xml configuration file of the Android project.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

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
#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

2 Integration in System Native Layer

Execute 1.1 and 1.2 of Integration in Unreal. For the rest of the initialization, refer to(https://crashsight.qq.com/docs/zh/crashsight/sdkDocuments/mobile-sdk.html “SDK Development and Integration for Mobile Applications open in new window.”)

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.

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.

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.

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.

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.

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.

3.7 Set Android Phone Model

public static void SetDeviceModel(const char *deviceModel)

Note: Set phone model

Note: Call it before the InitWithAppId interface.

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

View page:
extras: Crash Details->Trace Data->extraMessage.txt

Native stack: Crash Details->Trace Data->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

View page:

paramsJson: Crash Details->Trace Data->extraMessage.txt

Native stack: Crash Details->Trace Data->trace.zip

Other: time used to report the error

3.9 Set User ID

public static void SetUserId (const char *userId)

3.10 Mark a Scene

public static void SetScene (int sceneId)

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.

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.

View page: Crash Details->Trace Data->valueMapOthers.txt

3.13 Custom Log

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

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

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

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_UE4_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

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

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);
};

CSCrashCallBacks.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)
{
}

# 4.Integration Result Testing

CrashSight Test Interface

Test Java crash

static void TestJavaCrash();

Test Object-C crash

static void TestOcCrash();

Test Native crash

static void TestNativeCrash();

4.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

4.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.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 see Symbol Table Uploading Tools Guide.