• 1 Unreal引擎接入方案
  • 2 系统原生层接入方案
  • 3 接口说明
  • 4.接口说明(Windows)
  • 5.安卓额外操作
  • 6.接入结果测试
  • 7.上传符号表

Unreal SDK开发接入


本文是介绍Unreal SDK的详细文档,包含了基本的接入流程,和高级的接口使用介绍。
如果想快速接入,验证平台和SDK功能,建议查看项目菜单中的“接入引导”。引导中已经按项目具体的信息(平台,引擎,国内/海外,AppID)生成了针对此项目的初始化代码,可以直接复制使用。如下图所示:

项目创建:公司外部项目支持自助创建项目,但有免费试用时长。公司内部项目,企业微信联系“CrashSight小助手”开通。

本文档适用于当前稳定版本,Android、iOS及Windows平台可参考本文档接入。Xbox、PS4、PS5、Switch及Linux平台接入可参考新版Unreal SDK开发接入

1 Unreal引擎接入方案

1.1 导入 CrashSight UE Plugin

    1. 在平台成功创建项目后,在侧边栏的“接入指引”中,可以下载到与项目平台和引擎相匹配的SDK。如下图所示:
    1. 将位于同一目录中的 Plugins 文件解压,将 Plugins 文件夹中的CrashSight目录拷贝到UE项目根目录下的Plugins目录(如果没有则创建该文件夹)。点击[文件]刷新 [Visual Studio 项目],然后在 Visual Studio 项目中则可以看到CrashSight plugin 代码以及目录结构,如图所示。
    1. 将CrashSight插件源码和项目源码一起编译,编译完成后则可以在UE编辑器中的编辑插件中看到CrashSight插件,如图所示。

1.2 将CrashSight加入依赖项

在项目主模块的Build.cs中添加:

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

1.3 执行初始化

1.3.1 Android&iOS

  • 方法说明 选择第一个场景,或者主场景(scene), 在尽可能较早加载的脚本中调用如下代码进行初始化:
#include "CrashSightAgent.h" //请包含该头文件
#if DEBUG
        CrashSightAgent::ConfigDebugMode (true);
#endif
// 设置上报域名,请根据项目发行需求进行填写。(必填)
CrashSightAgent::ConfigCrashServerUrl("UploadUrl");
// 设置上报所指向的APP ID, 并进行初始化。APP ID可以在管理端更多->产品设置->产品信息中找到。(必填)
CrashSightAgent::InitWithAppId("AppID");  

  • 上报域名

国内公有云:

  • Android: https://android.crashsight.qq.com/pb/async
  • iOS: https://ios.crashsight.qq.com/pb/sync

海外公有云:

  • Android: https://android.crashsight.wetest.net/pb/async
  • iOS: https://ios.crashsight.wetest.net/pb/sync

1.3.2 Windows

方法说明 选择第一个场景,或者主场景(scene), 在尽可能较早加载的脚本中调用如下代码进行初始化:

#include "CrashSightBridgeWin.h" //请包含该头文件

CrashSight::CrashSightBridge::InitContext(UserId, AppVersion, CrashSightAppKeyForWindows);
// UserId和AppVersion可根据需要自行决定,APP Key可以在管理端更多->产品设置->产品信息中找到。

Windows平台还需添加崩溃捕获配置。崩溃捕获配置有2种方案,对于可以修改引擎的项目,强烈推荐使用1.3.2.1中的方案,崩溃上报更准确。对于其他使用官方引擎版本的用户,使用1.3.2.2中的配置。

1.3.2.1 接入方案1
  1. 在引擎源码 \Engine\Source\Runtime\Core\Public\Windows目录下,复制入CrashSightReporter.h
  2. 在引擎源码 \Engine\Source\Runtime\Core\Private\Windows\WindowsPlatformCrashContext.cpp 中引入CrashSightReporter.h,在函数ReportCrash(某些宏配置下为DefaultReportCrash)函数第一行,调用FCrashSightReporter::ReportCrashToCrashSight(ExceptionInfo);
  3. 编译引擎
  4. 在初始化函数CrashSight::CrashSightBridge::InitContext后调用 CrashSight::CrashSightBridge::SetVehEnable(false);
1.3.2.2 接入方案2
  1. 在初始化函数CrashSight::CrashSightBridge::InitContext后调用 CrashSight::CrashSightBridge::SetVehEnable(true);
  2. 在CrashSight::CrashSightBridge::SetVehEnable(true);后调用 CrashSight::CrashSightBridge::UnrealCriticalErrorEnable(true);

项目打包完成后,在CrashSight64.dll同级目录下创建TQM64/dump目录和GameBabyConfig64.dat文件(新建文本文档,然后修改后缀即可) GameBabyConfig64.dat文件需设置三个参数:
1)游戏进程exe名称,即GameName。
2)上报地址,即DomainUrl。
3)项目ID,即文件中的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 系统原生层接入方案

由于在引擎启动后初始化、完成信号处理函数注册时机较晚,导致之前的崩溃无法捕获,因此需要按以下方法提前初始化、完成信号注册。

需要执行Unreal引擎接入方案中的1.1, 1.2,然后在原生层初始化CrashSight。初始化参考代码如下:
Android:

import com.uqm.crashsight.core.api.crash.UQMCrash;

...
//先写入配置信息,此处只是示例
System.loadLibrary("CrashSight");
UQMCrash.configDebugModeBeforeInit(true);//开启debug
UQMCrash.setUserId("testUserId");//设置用户ID
UQMCrash.setAppVersion("testVersion");//设置版本


//再进行初始化
UQMCrash.configCrashServerUrlBeforeInit("https://android.crashsight.qq.com/rqd/pb/async");//这是国内的上报域名
UQMCrash.initWithAppId("******");

iOS:

#include "CrashSight/CrashSightCore.framework/Headers/CrashSightAgent.h"

...
//先写入配置信息,此处只是示例,具体配置接口可参考CrashSightAgent.h
GCloud::CrashSight::CrashSightAgent::ConfigDebugMode(true);//开启debug
GCloud::CrashSight::CrashSightAgent::SetUserId("testUserId");//设置用户ID
GCloud::CrashSight::CrashSightAgent::SetAppVersion("testVersion");//设置版本


//再进行初始化
GCloud::CrashSight::CrashSightAgent::ConfigCrashServerUrl("https://ios.crashsight.qq.com/pb/sync");//这是国内的上报域名
GCloud::CrashSight::CrashSightAgent::InitWithAppId("******");

3 接口说明

3.1 初始化

public static void InitWithAppId (string appId)

说明: 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。

参数类型说明
appIdstring已注册项目的APP ID

3.2 debug使能开关

public static void ConfigDebugMode (bool enable)

说明:是否开启debug模式,默认为关。开启后会打印一定量的日志,但是可以方便测试期间的问题定位。

备注:需要在InitWithAppId接口之前调用。

参数类型说明
enablebooldebug使能开关

3.3 上报域名设置

public static void ConfigCrashServerUrl (const char * crashServerUrl)

说明:设置上报域名。

备注:需要在InitWithAppId接口之前调用。

国内公有环境域名如下:

  • 安卓: https://android.crashsight.qq.com/pb/async

  • iOS: https://ios.crashsight.qq.com/pb/sync

直接接入CrashSight域名与MSDK转接不同,请务必重新依照上述域名配置。其他环境域名请咨询接入接口人。

参数类型说明
crashServerUrlconst char *要上报的域名

3.4 设置自定义日志上报级别

public static void ConfigCrashReporter (int logLevel)

说明:设置自定义日志上报级别 Off=0,Error=1,Warn=2,Info=3,Debug=4

备注:需要在InitWithAppId接口之前调用。

参数类型说明
logLevelint日志级别

3.5 设置渠道、应用版本、用户ID、延迟初始化

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

备注:需要在InitWithAppId接口之前调用。

参数类型说明
channelconst char *渠道
versionconst char *应用版本
userconst char *用户ID
delaylong延迟(s)

3.6 设置Android设备ID

public static void SetDeviceId(const char *deviceId)

说明:从4.2.9版本开始,CrashSight Android不再获取AndroidId,默认采用uuid作为设备ID

备注:需要在InitWithAppId接口之前调用。

参数类型说明
deviceIdconst char *设备ID

3.7 设置Android手机型号

public static void SetDeviceModel(const char *deviceModel)

说明:设置手机型号

备注:需要在InitWithAppId接口之前调用。

参数类型说明
deviceModelconst char *手机型号

3.8 上报错误

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

说明: 主动上报错误信息

参数类型说明
typeint异常类型, C#: 4, js: 5, lua: 6
nameconst char *异常名称
reasonconst char *异常信息
stackTraceconst char *堆栈
extrasconst char *其他信息
quitbool是否退出
isDumpNativeStackbool是否dump当前线程的Native堆栈

页面查看:

extras:崩溃详情页->附件下载->extraMessage.txt

Native堆栈:崩溃详情页->附件下载->trace.zip

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

说明: 主动上报错误信息

参数类型说明
typeint异常类型, C#: 4, js: 5, lua: 6
exceptionNameconst char *异常名称
exceptionMsgconst char *异常信息
exceptionStackconst char *堆栈
paramsJsonconst char *其他信息, map编码的Json字符串
quitbool是否退出
isDumpNativeStackbool是否dump当前线程的Native堆栈

页面查看:

paramsJson:崩溃详情页->附件下载->extraMessage.txt

Native堆栈:崩溃详情页->附件下载->trace.zip

其它:上报错误耗时

AndroidiOS
附件大小dump堆栈不dump堆栈dump堆栈不dump堆栈
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 设置用户ID

public static void SetUserId (const char *userId)

说明: 设置用户ID,请在初始化之后调用。

参数类型说明
userIdconst char *用户ID

3.10 标记场景

public static void SetScene (int sceneId)

说明: 设置用户ID

参数类型说明
sceneIdint场景ID

3.11 设置应用版本

static void SetAppVersion(const char *appVersion)

说明:设置应用版本号

Android 默认使用AndroidManifest.xml文件的versionName属性

iOS 配置Info.plist, {CFBundleShortVersionString}.{CFBundleVersion} 组合成app版本号

备注:需要在InitWithAppId接口之前调用。

参数类型说明
appVersionconst char *版本号

3.12 添加自定义数据

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

说明:设置用户自定义的 Key-Value 数据,将在发送 Crash 时随异常信息一起上报,单个key长度限制100字符,单个value限制1000字符,总长度(所有key+value)限制(Android 64KB,iOS 128KB)。支持在回调中使用。

页面查看:崩溃详情页->附件下载->valueMapOthers.txt

参数类型说明
keyconst char *
valueconst char *

3.13 自定义日志

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

说明:自定义日志,限制30KB。安卓不支持在崩溃回调中写入自定义日志。

参数类型说明
levelLogSeverity日志级别
formatconst char *日志格式

3.14 设置回调

public static void SetCrashObserver(UQMCrashObserver *crashObserver)

说明: 回调函数在捕获到崩溃时调用。自定义CSCrashCallBack类,继承UQMCrashObserver,实现OnCrashExtraMessageNotify、OnCrashExtraDataNotify方法

参数类型说明
crashObserverUQMCrashObserverUQMCrashObserver实现

示例如下:

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字符,超过会截断
    strcpy(retValue, str1);
    return retValue;
}

long CSCrashCallBacks::OnCrashExtraDataNotify(const InnerCrashRet &crashRet) {
    char str[] = "this is extra data.";
    strcpy(crashRet.data, str); //已经分配 128*1024 byte内存,无需再分配,超过会截断
    return strlen(str);
}

Android OnCrashExtraMessageNotify 返回的内容在页面“崩溃详情页->附件下载-extraMessage.txt” Android OnCrashExtraDataNotify 返回的内容在页面“崩溃详情页->附件下载-userExtraByteData”,Base64编码 iOS OnCrashExtraMessageNotify返回的内容在页面“崩溃详情页->附件下载-crash_attach.log” iOS 不调用OnCrashExtraDataNotify接口

3.15 设置上传日志路径

public static void SetLogPath(const char *logPath)

说明:设置崩溃后上传的日志路径,需要可读权限

参数类型说明
logPathconst char *日志绝对路径

3.16 设置日志上传回调

页面查看: 崩溃详情-跟踪数据-客户端上报log

public static void SetCrashLogObserver(UQMCrashLogObserver *crashObserver)

说明: 回调函数在上传日志时调用。自定义 MyCrashLogCallback 类,继承UQMCrashLogObserver,实现OnCrashSetLogPathNotify、OnCrashLogUploadResultNotify方法

参数类型说明
crashObserverUQMCrashLogObserverUQMCrashLogObserver的子类

示例如下:

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();
    
    // 设置日志路径回调
    const char* OnCrashSetLogPathNotify(int crashType);

    // 通知日志上传结果回调
    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()
{
}

// 设置日志路径回调
// @param crashType 崩溃类型,0:Java崩溃,2:Native崩溃
// @result 日志的绝对路径,如果非空覆盖SetCrashLogObserver接口设置的路径
const char *MyCrashLogCallback::OnCrashSetLogPathNotify(int crashType)
{
    const char *path = "/data/data/packagename/app_crashSight/log.txt";
    return path;
}

// 通知日志上传结果回调
// @param crashType 崩溃类型,0:Java崩溃,2:Native崩溃
// @param retust 日志上传结果, 0:成功,其它:失败
void MyCrashLogCallback::OnCrashLogUploadResultNotify(int crashType, int result)
{
}

3.17 设置上报的Android Locat大小

public static void SetLogcatBufferSize(int size)

说明:设置崩溃和错误时上传的logcat日志大小,仅Android有效。建议设置不超过128KB。默认值为30KB。

参数类型说明
sizeintlogcat日志大小,单位byte

4.接口说明(Windows)

4.1 初始化

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

说明: 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。

参数类型说明
userIdstring用户Id
versionstring版本号
keystring已注册项目的APP key

4.2 主动上报错误

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

说明:主动上报错误

参数类型说明
typeint异常类型, C#: 4, js: 5, lua: 6
exp_nameconst char *异常名称
exp_messageconst char *异常信息
stack_traceconst char *堆栈
extrasconst char *其他信息
is_asyncbool是否异步
error_attach_pathconst char *附件的绝对路径(不支持GBK字符)
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);

说明:主动上报错误

参数类型说明
typeint异常类型, C#: 4, js: 5, lua: 6
exp_nameconst char *异常名称
exp_messageconst char *异常信息
stack_traceconst char *堆栈
extrasconst char *其他信息
is_asyncbool是否异步
error_attach_pathconst wchar_t *附件的绝对路径

4.3 添加自定义数据

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

说明:设置用户自定义的 Key-Value 数据,将在发送 Crash 时随异常信息一起上报,单个key长度限制100字符,单个value限制1000字符

页面查看:崩溃详情页->Value Map

参数类型说明
keyconst char *
valueconst char *

4.4 设置自定义日志路径

static void SetCustomLogDir(const char *log_path);

页面查看:崩溃详情页->自定义日志(来自文件)

参数类型说明
log_pathconst char *日志路径(不支持GBK字符)
static void SetCustomLogDirW(const wchar_t *log_path);

页面查看:崩溃详情页->自定义日志(来自文件)

参数类型说明
log_pathconst wchar_t *日志路径

4.5 设置用户ID

static void SetUserId(const char *user_id);
参数类型说明
user_idconst char *用户ID

4.6 添加自定义日志

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

说明:自定义日志,限制30KB

参数类型说明
levelCSLogSeverity日志级别
tagconst char *日志标签
formatconst char *日志格式
argsparams object[]可变参数

4.7 启用Veh异常处理

static void SetVehEnable(bool enable);
参数类型说明
enableboolVeh异常处理开关

4.8 主动上报崩溃

static void ReportCrash();

说明:主动上报一条崩溃信息

4.9 主动上报dump

static void ReportDump(const char *dump_path, bool is_async);
参数类型说明
dump_pathconst char *dump目录
is_asyncbool是否强制退出程序

4.10 设置崩溃回调

static void SetCrashCallback(CrashCallbackFuncPtr callback);
参数类型说明
callbackCrashCallbackFuncPtr崩溃回调函数指针

回调函数定义为:

typedef void (*CrashCallbackFuncPtr)(int type, const char *guid);
参数类型说明
typeint崩溃的类型
guidconst char *客户端侧上报ID

4.11 开启额外异常捕获

static void SetExtraHandler(bool extra_handle_enable);

说明:设置额外的异常处理机制,默认为关闭,与旧版保持一致。 开启后,可以捕获上报strcpy_s一类的安全函数抛出的非法参数崩溃,以及,虚函数调用purecall错误导致的崩溃。

参数类型说明
extra_handle_enablebool额外异常捕获开关

4.12 上传dump文件

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

说明:上传指定路径下的dump文件

参数类型说明
dump_dirconst char *dump文件地址
is_extra_checkbool默认填false即可

4.13 UE Critical Error上报

static void UnrealCriticalErrorEnable(bool enable);

说明:设定是否上报UE的Critical Error

参数类型说明
enableboolUE Critical Error上报开关

4.14 仅上报首条崩溃开关

static void OnlyUploadFirstCrash(bool enable);

说明:开启后,每次启动仅会上报首个捕获的崩溃,防止重复上报。仅在VEH捕获关闭时生效

参数类型说明
enablebool仅上报首条崩溃开关

5.安卓额外操作

5.1 开启Critical Error上报

在Android平台上,Unreal引擎将Critical Error的退出方式设为正常退出,导致CrashSight无法直接捕获这一类崩溃。为了捕获Critical Error,需要找到UE引擎代码如下位置:


FPlatformMisc::RequestExit(true);

改为

abort();

iOS的Critical Error是以崩溃方式退出,因此无需更改。

5.2 UE5.1及以上unwind问题修复

Unreal engine 5.1及以上打包的Android项目会出现unwind崩溃问题,导致native crash上报失败。如果可能,请尽快将引擎升级到更新的版本以彻底杜绝这个问题发生。以下是通过修改源码来避免unwind崩溃问题的方法:

6.接入结果测试

CrashSight测试接口

测试Java崩溃(仅Android)

static void TestJavaCrash();

测试Object-C崩溃(仅iOS)

static void TestOcCrash();

测试Native崩溃(Android&iOS)

static void TestNativeCrash();

6.1. iOS测试方法:

  • a. 开启Debug模式,初始化CrashSight,并给定合适的配置参数
  • b. 联网上报:检查测试设备日志中是否打印“begin to upload <CSAnalyticsLogic” 或者 “cmd: 641”
  • c. 崩溃捕获:检查测试设备日志中是否打印“Handle the crash scene in callback”
  • d. 上报异常:检查测试设备日志中是否打印“begin to upload <CSCrashLogic” 或者 “cmd: 631”

6.2. Android测试方法:

  • a. 开启Debug模式,初始化CrashSight,并给定合适的配置参数
  • b. 联网上报:检查logcat日志是否打印“[Upload] Run upload task with cmd: 840”
  • c. 崩溃捕获:检查logcat日志是否打印“HandleSignal start”
  • d. 上报异常:检查logcat日志是否打印"[Upload] Run upload task with cmd: 830"

6.3. Windows测试方法:

  • a.初始化CrashSight后,联网上报是否正常,具体验证方法如下:

    1. 初始化CrashSight;
    2. 5分钟后,在管理端页面的 异常概览 --> 崩溃趋势 --> 联网设备数 中可以看到统计数值大于等于1.
  • b.游戏发生崩溃,是否能正确上报,具体验证方法如下:

    1. 初始化CrashSight;
    2. 在游戏内可以由以下代码触发崩溃。(其他类似的坏内存访问也可以)
    int* a = 0;
    a[10000] = 5;
    
  • c.查看TQM64/dump路径下是否有dmp文件生成。如果没有,说明无法成功捕获崩溃,请联系CrashSight开发.

  • d.查看管理端页面 “崩溃分析”页上,是否有对应时间点的上报。如果3有,4没有,说明没有成功上报。请检查APPID配置(两个配置文件均要正确),以及APP KEY配置,是否对应且与应用设置中一样。如果配置正确,还无法上报,请联系CrashSight开发.

  • e.崩溃上报的版本号,用户名是否与设置一致.

  • f.错误上报的版本号,用户名是否与设置一致.

7.上传符号表

以上内容介绍了SDK的接入,崩溃上报和验证,但要在页面上看到可读的还原堆栈,还需要上传对应的符号表,请见 符号表上传工具使用说明

Last Updated: