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