Unreal接入指引(Linux DS)
本文是介绍Linux DS平台的Unreal SDK详细文档，包含了基本的接入流程，和高级的接口使用介绍。
1 Unreal引擎接入方案
1.1 导入 CrashSight UE Plugin
-
- CrashSight Linux DS SDK目前不开放下载链接，请企业微信联系“CrashSight小助手”获取SDK包。
-
- 将位于同一目录中的 Plugins 文件解压，将 Plugins 文件夹中的CrashSight目录拷贝到UE项目根目录下的Plugins目录（如果没有则创建该文件夹）。点击[文件]刷新 [Visual Studio 项目]，然后在 Visual Studio 项目中则可以看到CrashSight plugin 代码以及目录结构，如图所示。
-
- 将CrashSight插件源码和项目源码一起编译，编译完成后则可以在UE编辑器中的编辑插件中看到CrashSight插件，如图所示。
1.2 将CrashSight加入依赖项
在项目主模块的Build.cs中添加：
PrivateDependencyModuleNames.AddRange(new string[] { "CrashSight" });
1.3 执行初始化
- 方法说明 选择第一个场景，或者主场景（scene）， 在尽可能较早加载的脚本中调用如下代码进行初始化：
#include "CrashSightAgent.h" //请包含该头文件
#if DEBUG
CrashSightAgent::ConfigDebugMode (true);
#endif
// 设置上报域名，请根据项目发行需求进行填写。（必填）
CrashSightAgent::ConfigCrashServerUrl("UploadUrl");
// 设置上报所指向的APP ID、APP Key和版本号, 并进行初始化。APP ID和APP Key可以在管理端更多->产品设置->产品信息中找到。
CrashSightAgent::Init(CrashSightAppId, CrashSightAppKey, AppVersion);
- 上报域名
国内公有云：pc.crashsight.qq.com
海外公有云：pc.crashsight.wetest.net
2 接口说明
2.1 初始化
static void InitWithAppId(const char* app_id);
说明： 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。 appid是CrashSight对项目的唯一标识，可以在产品设置->产品信息中查看。
| 参数 | 类型 | 说明 |
|---|---|---|
| app_id | const char* | 已注册项目的APP ID |
2.2 上报错误
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);
说明： 主动上报错误信息。可以在捕获到错误或者需要上报的时候手动调用，支持多线程调用。 name、reason和stack_trace不能为null。
| 参数 | 类型 | 说明 |
|---|---|---|
| type | int | 异常类型, C#: 4, js: 5, lua: 6 |
| name | const char * | 异常名称 |
| reason | const char * | 异常信息 |
| stack_trace | const char * | 堆栈 |
| extras | const char * | 其他信息 |
| quit | bool | 是否退出 |
| dump_native_type | int | 无效，填0即可 |
页面查看：
extras：崩溃详情页->附件下载->extraMessage.txt
2.3 设置用户ID
static void SetUserId(const char* user_id);
说明： 设置用户ID。用户id默认为unknown。
| 参数 | 类型 | 说明 |
|---|---|---|
| user_id | const char * | 用户ID |
2.4 添加自定义数据
static void AddSceneData(const char* key, const char* value);
说明：设置用户自定义的 Key-Value 数据，将在发送 Crash 时随异常信息一起上报。总长度最多支持128k。
页面查看：崩溃详情页->附件下载->valueMapOthers.txt
| 参数 | 类型 | 说明 |
|---|---|---|
| key | const char * | 键 |
| value | const char * | 值 |
2.5 设置应用版本
static void SetAppVersion(const char* app_version);
说明：设置应用版本号
| 参数 | 类型 | 说明 |
|---|---|---|
| app_version | const char * | 版本号 |
2.6 上报域名设置
static void ConfigCrashServerUrl(const char* crash_server_url);
说明：设置上报域名。
备注：需要在Init接口之前调用。
上报域名如下：
国内公有云：pc.crashsight.qq.com
海外公有云：pc.crashsight.wetest.net
直接接入CrashSight域名与MSDK转接不同，请务必重新依照上述域名配置。其他环境域名请咨询接入接口人。
| 参数 | 类型 | 说明 |
|---|---|---|
| crash_server_url | const char * | 要上报的域名 |
2.7 设置上传日志路径
static void SetLogPath(const char* log_path);
说明：设置崩溃后上传的日志路径，需要可读权限。附件最大支持8MB。
| 参数 | 类型 | 说明 |
|---|---|---|
| log_path | const char * | 日志绝对路径 |
2.8 debug使能开关
static void ConfigDebugMode(bool enable);
说明：是否开启debug模式，默认为关。开启后会打印一定量的日志，但是可以方便测试期间的问题定位。
备注：需要在Init接口之前调用。
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | debug使能开关 |
2.9 设置设备ID
static void SetDeviceId(const char* device_id);
说明：设置设备ID，默认采用uuid作为设备ID
备注：需要在Init接口之前调用。
| 参数 | 类型 | 说明 |
|---|---|---|
| device_id | const char * | 设备ID |
2.10 自定义日志
static void PrintLog(LogSeverity level, const char* format, ...);
说明：自定义日志，限制30KB
| 参数 | 类型 | 说明 |
|---|---|---|
| level | LogSeverity | 日志级别 |
| format | const char * | 日志格式 |
| args | params object[] | 可变参数 |
自定义日志查看：问题详情->自定义日志（来自接口）
2.11 设置所有记录文件的路径
static void SetRecordFileDir(const char* record_dir);
说明：设置所有记录文件的路径，包括SDK日志和dump文件，默认为当前可执行文件的目录下。
| 参数 | 类型 | 说明 |
|---|---|---|
| record_dir | const char* | 记录文件路径 |
3.接入结果测试
请参照以下步骤验证接入是否成功：
- a. 以Debug模式初始化
CrashSightAgent::ConfigDebugMode (true);
CrashSightAgent::ConfigCrashServerUrl("UploadUrl");
CrashSightAgent::Init(CrashSightAppId, CrashSightAppKey, AppVersion);
- b. 上报一个错误
CrashSightAgent::ReportException(4, "name", "message", "stackTrace", "", false, 0);
- c. 触发一个崩溃
int* a = NULL;
a[10000] = 5;
- d. 查看本地日志 libCrashSight.so同目录下会生成crashsight_data文件夹，里面存放了本地日志。 按照之前的步骤，初始化、错误、崩溃时分别会上报一次数据，请根据时间戳检查对应时间点是否有“response code is 200”。返回200表示上报成功；如果返回值为-1，则是网络不通；其它返回值可能为服务器拒绝，请检查初始化时appid、appkey和url是否填写正确。
- e. 检查上报的信息 查看管理端页面 “崩溃分析”页和“错误分析”页上，是否有对应时间点的上报。
4.上传符号表
以上内容介绍了SDK的接入方法和接口使用细节，但要在页面上看到可读的还原堆栈，还需要上 传对应的符号表。
4.1 所需文件
Unreal打包前须勾选 文件-打包项目-打包设置【包括调试文件】，上传符号表需要2个文件：
- 可执行文件或so文件
- 与可执行文件或so文件同名的.debug文件
4.2 流水线插件上传符号表
DS项目目前只支持蓝盾流水线上传符号表，请搜索并添加CrashSight符号表上传工具，并根据以下指示进行配置：
- 上传符号表地址选择自定义环境，URL一栏填写crashsight.qq.com。
- bundleId填写empty
- 版本号根据当次构建进行填写
- 根据产品设置->产品信息中展示的appId和appKey创建凭证，并在下拉框中选择
- 平台类型选择Linux.sym
- 待上传符号表所在文件夹或文件路径一栏，填写4.1中所示文件的路径
- 其余选项无需改动
配置完成后运行流水线，即可完成符号表上传