Unity接入指引
本文是介绍Unity SDK的详细文档,包含了基本的接入流程,和高级的接口使用介绍,以及针对Unity引擎如何更早进行初始化等内容。
如果想快速接入,验证平台和SDK功能,建议查看项目菜单中的“接入指南”。引导中已经按项目具体的信息(平台,引擎,国内/海外,AppID)生成了针对此项目的初始化代码,可以直接复制使用。如下图所示:
项目创建:公司外部项目支持自助创建项目,但有免费试用时长。公司内部项目,企业微信联系“CrashSight小助手”开通。
本文档适用于CrashSight SDK 4.3.x版本。4.2.x版本接入请参考旧版本Unity SDK开发接入
1 Unity引擎C#接入方案
1.1 下载并导入Unity Plugin到Unity项目工程
在平台成功创建项目后,在侧边栏的“接入指南”中,可以下载到与项目平台和引擎相匹配的SDK。如下图所示:
1.2 初始化CrashSight
选择第一个场景,或者主场景(scene), 在尽可能较早加载的脚本中调用如下代码进行初始化:
// Debug开关,Debug模式下会打印更多便于问题定位的Log.
#if DEBUG
CrashSightAgent.ConfigDebugMode (true);
#endif
// 设置应用版本号 (必填)
CrashSightAgent.SetAppVersion("appVersion");
// 设置上报的目标域名,请根据项目需求进行填写。(必填)
CrashSightAgent.ConfigCrashServerUrl (CrashSightUploadUrl);
// 设置上报所指向的APP ID, 并进行初始化。APP ID可以在管理端更多->产品设置->产品信息中找到。
CrashSightAgent.InitWithAppId(CrashSightAppID);
上报域名
国内公有云:
- Android: https://android.crashsight.qq.com/pb/async
- iOS: https://ios.crashsight.qq.com/pb/sync
- Harmony: harmony.crashsight.qq.com
- Windows: pc.crashsight.qq.com
- Mac: https://mac.crashsight.qq.com/pb/sync
海外公有云
- 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.3.1 iOS集成配置
- 1)在Unity中修改项目的偏好设置(Build Settings) a. 按下 Ctrl+Shift+B打开Build Settings面板, 点击Player Settings切换到Setting for iOS选项卡,选择Other Settings栏,修改Optimization配置项Script Call Optimization的值为Slow and Safe
- 2)修改导出的Xcode工程的编译配置,切换到Build Phases选项卡, 在Link Binary With Libraries栏目下添加如下依赖性:
- libc++.dylib 或 libc++.tdb 用于引入c++标准库
- libz.dylib 或 libz.tdb 用于对上报的数据进行压缩
- Security.framework 用于存储keychain
- SystemConfiguration.framework 用于读取异常发生时的系统信息
- MetricKit.framework 用于获取apple提供的app诊断信息(弱引用,请选择“optional”)
- OSLog.framework 用于获取NSLog日志信息(弱引用,请选择“optional”)
- CFNetwork.framework 用于获取VPN状态
注意:
- i. 如果项目已经添加过这些依赖项,不用重复添加。
- ii. 通过XUPorter集成无需在Xcode中添加配置。
1.3.2 安卓集成配置(配置native库提取)
未提取的native库会导致获取的崩溃堆栈无法还原。这种情况的表现为,堆栈中的崩溃模块是xx.apk而非xx.so,不能定位到具体的库。
为了避免未提取的native库对堆栈还原造成影响,请做如下配置:
(1)打包APK时,前往Project Settings -> Player -> Build,勾选Custom Main Manifest,并在AndroidManifest.xml中配置android:extractNativeLibs="true"
<application
...
android:extractNativeLibs="true">
(2)打包AAB时,前往Project Settings -> Player -> Build,勾选Custom Gradle Properties Template,并在gradleTemplate.properties中添加:
enableUncompressedNativeLibs = false
通过添加此参数,操作系统可以在应用程序崩溃时提供额外的信息,以帮助分析崩溃的原因。
1.3.3 鸿蒙集成配置
在导出Dev Eco工程以后,需要把CrashSightBridge.ts改名为CrashSightBridge.ets,然后再进行打包。
1.4 Unity 接入演示
- 1)双击下载好的插件中的CrashSightPlugin.unitypackage包,在Unity中出现如下界面,导入插件。
- 2)初始化。
private const string CrashSightAppIDForiOS = "685a68759e";
private const string CrashSightAppIDForAndroid = "e6af377f84";
private const string CrashSightUploadUrliOS = "https://ios.crashsight.qq.com/pb/sync";
private const string CrashSightUploadUrlAndroid = "https://android.crashsight.qq.com/pb/async";
CrashSightAgent.ConfigDebugMode (true);
CrashSightAgent.SetAppVersion("appVersion");
#if UNITY_IPHONE || UNITY_IOS
CrashSightAgent.ConfigCrashServerUrl(CrashSightUploadUrliOS);
CrashSightAgent.InitWithAppId(CrashSightAppIDForiOS);
#elif UNITY_ANDROID
CrashSightAgent.ConfigCrashServerUrl(CrashSightUploadUrlAndroid);
CrashSightAgent.InitWithAppId(CrashSightAppIDForAndroid);
#endif
1.5 接入结果测试
CrashSight测试接口
测试Java崩溃(Android)
static void TestJavaCrash();
测试Object-C崩溃(iOS)
static void TestOcCrash();
测试Native崩溃(Android&iOS,未来将支持全平台)
static void TestNativeCrash();
测试OOM崩溃(Android、iOS)
static void TestOomCrash();
测试ANR(仅Android)
static void TestANR();
测试释放后使用内存,仅GWP_Asan或MTE功能启用后生效(Android)
static void TestUseAfterFree();
强制Unity崩溃(全平台可用)
UnityEngine.Diagnostics.Utils.ForceCrash(ForcedCrashCategory.AccessViolation);
1.5.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”
1.5.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"
1.5.3 Windows测试方法
-
a.初始化CrashSight后,联网上报是否正常,具体验证方法如下:
- 初始化CrashSight;
- 5分钟后,在管理端页面的 异常概览 --> 崩溃趋势 --> 联网设备数 中可以看到统计数值大于等于1.
-
b.游戏发生崩溃,是否能正确上报,具体验证方法如下:
- 初始化CrashSight;
- 在游戏内可以由以下代码触发崩溃。(其他类似的坏内存访问也可以)
int* a = NULL;
a[10000] = 5; -
c.查看CrashSight64/dump目录(旧版本为TQM64/dump)下是否有dmp文件生成。如果没有,说明无法成功捕获崩溃,请联系CrashSight开发.
-
d.查看管理端页面 “崩溃分析”页上,是否有对应时间点的上报。如果3有,4没有,说明没有成功上报。请检查APPID配置(两个配置文件均要正确),以及APP KEY配置,是否对应且与应用设置中一样。如果配置正确,还无法上报,请联系CrashSight开发.
-
e.崩溃上报的版本号,用户名是否与设置一致.
-
f.错误上报的版本号,用户名是否与设置一致.
1.6 上传符号表
以上内容介绍了SDK的接入,崩溃上报和验证,但要在页面上看到可读的还原堆栈,还需要上传对应的符号表,请见符号表上传工具使用说明
1.7 配置usym还原
此步骤可以为il2cpp模块的堆栈行补充C#文件名和行号信息。目前支持Android和iOS平台。
项目打包前
使用Unity6项目只需改变一个设置项。前往Project Settings->Player->Android->Other Settings->IL2CPP StackTrace Information,将选项设置为“Method Name, File Name, and Line Number”
使用Unity2022及以下的项目需要替换usymtool。由于只有Unity6版本的usymtool支持输出可用的usym文件,所以需要从Unity6复制一份usymtool到当前使用的引擎中。
在Windows平台上打包时,usymtool的位置是:PathToUnityEngine\Editor\Data\Tools\usymtool.exe
在Mac平台上打包时,usymtool的位置是:PathToUnityEngine/Contents/Tools/macosx/usymtool
对于使用Unity2022及以下的项目,替换usymtool可以支持对崩溃堆栈的usym还原,如果需要还原C#异常上报的堆栈或UnityLog错误上报的堆栈,则需额外修改部分引擎源码。请参考下面的代码修改PathToUnityEngine/Data/il2cpp/libil2cpp/icalls/mscorlib/System.Diagnostics/StackTrace.cpp:
#if !IL2CPP_TINY
#include "il2cpp-config.h"
#include "il2cpp-class-internals.h"
#include "il2cpp-object-internals.h"
#include "gc/WriteBarrier.h"
#include "vm/Array.h"
#include "vm/Object.h"
#include "vm/Reflection.h"
#include "icalls/mscorlib/System.Diagnostics/StackTrace.h"
#include "vm-utils/DebugSymbolReader.h"
#include "vm/String.h"
namespace il2cpp
{
namespace icalls
{
namespace mscorlib
{
namespace System
{
namespace Diagnostics
{
static Il2CppArray* GetTraceInternal(Il2CppException* exc, int32_t skip, bool need_file_info)
{
Il2CppArray* trace_ips = exc->trace_ips;
Il2CppArray* nativetrace_ips = exc->native_trace_ips;
/* Exception is not thrown yet */
if (trace_ips == NULL)
return vm::Array::New(il2cpp_defaults.stack_frame_class, 0);
int len = vm::Array::GetLength(trace_ips);
Il2CppArray* stackFrames = vm::Array::New(il2cpp_defaults.stack_frame_class, len > skip ? len - skip : 0);
for (int i = skip; i < len; i++)
{
Il2CppStackFrame* stackFrame = NULL;
if (utils::DebugSymbolReader::DebugSymbolsAvailable())
{
stackFrame = il2cpp_array_get(trace_ips, Il2CppStackFrame*, i);
}
else
{
stackFrame = (Il2CppStackFrame*)vm::Object::New(il2cpp_defaults.stack_frame_class);
MethodInfo* method = il2cpp_array_get(trace_ips, MethodInfo*, i);
IL2CPP_OBJECT_SETREF(stackFrame, method, vm::Reflection::GetMethodObject(method, NULL));
uintptr_t fileNamePtr = il2cpp_array_get(nativetrace_ips, uintptr_t, i);
char buffer[32];
snprintf(buffer, sizeof(buffer), "0x%x", fileNamePtr);
stackFrame->filename = il2cpp::vm::String::New(buffer);
}
il2cpp_array_setref(stackFrames, i, stackFrame);
}
return stackFrames;
}
Il2CppArray* StackTrace::get_trace(Il2CppException *exc, int32_t skip, bool need_file_info)
{
// Exception.RestoreExceptionDispatchInfo() will clear trace_ips, so we need to ensure that we read it only once
return GetTraceInternal(exc, skip, need_file_info);
}
} /* namespace Diagnostics */
} /* namespace System */
} /* namespace mscorlib */
} /* namespace icalls */
} /* namespace il2cpp */
#endif
项目打包后
安卓平台的usym文件是libil2cpp.usym.so。可以在构建出的apk文件中解压出libil2cpp.usym.so,或者在项目的Library\Bee\Android\Prj\IL2CPP目录下搜索libil2cpp.usym.so。
iOS平台的usym文件是libil2cpp.usym。可以在xcode项目的目录下找到/Data/Managed/il2cpp.usym。
使用蓝盾插件将usym文件上传至CrashSight后台,平台类型请选择“安卓Usym”或“iOS Usym”(目前尚不支持蓝盾以外的方式上传,如果项目不使用蓝盾流水线,请联系CrashSight项目组寻求帮助)
2 系统原生层接入Unity引擎方案(Android&iOS)
2.1 下载并导入Unity Plugin到Unity项目工程
在平台成功创建项目后,在侧边栏的“接入指南”中,可以下载到与项目平台和引擎相匹配的SDK。如下图所示:
2.2 SDK初始化
在原生层初始化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("******");
2.3 安卓重注册
由于Unity 5以后的兼容性问题,在原生层进行初始化后,安卓需要在C#进行一次重注册,iOS暂时无需操作。 重注册函数: CrashSightAgent.ReRegistAllMonitors(); 在C#层脚本的尽可能早的位置执行该函数即可。
2.4 上报Unity Log Error(可选)
如果项目想将Unity Log Error作为错误上报到CrashSight,可以通过调用CrashSightAgent.EnableExceptionHandler() ;开启该功能。需要注意的是,开启该功能后请尽量控制项目中Unity Log Error的触发频率。
2.5 发生崩溃/错误时的回调。(可选)
如果项目想在发生崩溃/错误时,在上报信息中加入一些内容,可以通过处理回调加入相关内容。 需要注意的是:
-
- 回调中的处理请尽可能保证线程安全,防止二次崩溃的发生。发生二次崩溃后,当前崩溃无法在本次完成上报,条件允许的情况下,下次启动会进行上报,但是不会包含回调内容。
-
- 回调的信息请遵守合规要求。
3 C#接口说明
全平台接口是指所有平台都通用的接口,覆盖了CrashSight的大部分基础功能,如:初始化、错误上报等。此外,每个平台可能会有一些独有的接口,会在后文单独列出。一个平台上可以使用的全部接口为:全平台接口+该平台独有的接口。
3.1 全平台接口
3.1.1 初始化
public static void InitWithAppId(string appId);
说明: 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。 appid是CrashSight对项目的唯一标识,可以在产品设置->产品信息中查看。
参数 | 类型 | 说明 |
---|---|---|
appId | string | 已注册项目的APP ID |
3.1.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, int dumpNativeType = 0, string errorAttachmentPath = "");
说明: 主动上报错误信息。可以在捕获到错误或者需要上报的时候手动调用,支持多线程调用。 exceptionName、exceptionMsg和exceptionStack不能为null。
参数 | 类型 | 说明 |
---|---|---|
type | int | 异常类型, 0~3为内部保留类型传入无效, C#: 4, js: 5, lua: 6 |
exceptionName | string | 异常名称 |
exceptionMsg | string | 异常信息 |
exceptionStack | string | 堆栈 |
extInfo | Dictionary<string, string> | 其他信息 |
dump_native_type | int | 0:关闭,1:调用系统接口dump,3:minidump(仅移动端有效) |
errorAttachmentPath | string | 日志附件的绝对路径(仅Android有效) |
页面查看:
extras:崩溃详情页->附件下载->extraMessage.txt
Native堆栈:崩溃详情页->附件下载->trace.zip
其它:上报错误耗时
Android | iOS | |||
---|---|---|---|---|
附件大小 | 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.1.3 设置用户ID
public static void SetUserId(string userId);
说明: 设置用户ID。用户id默认为unknown。
参数 | 类型 | 说明 |
---|---|---|
userId | string | 用户ID |
3.1.4 添加自定义数据
public static void AddSceneData(string key, string value);
说明:设置用户自定义的 Key-Value 数据,将在发送 Crash 时随异常信息一起上报,单个key长度限制100字符,单个value限制1000字符,总长度(所有key+value)限制(Android 64KB,iOS 128KB)
页面查看:崩溃详情页->附件下载->valueMapOthers.txt
参数 | 类型 | 说明 |
---|---|---|
key | string | 键 |
value | string | 值 |
3.1.5 设置应用版本
public static void SetAppVersion(string appVersion);
说明:设置应用版本号
Android 默认使用AndroidManifest.xml文件的versionName属性
iOS 配置Info.plist, {CFBundleShortVersionString}.{CFBundleVersion} 组合成app版本号
备注:需要在InitWithAppId接口之前调用。
参数 | 类型 | 说明 |
---|---|---|
appVersion | string | 版本号 |
3.1.6 上报域名设置
public static void ConfigCrashServerUrl(string crashServerUrl);
说明:设置上报域名。
备注:需要在InitWithAppId接口之前调用。
国内公有环境域名如下:
直接接入CrashSight域名与MSDK转接不同,请务必重新依照上述域名配置。其他环境域名请咨询接入接口人。
参数 | 类型 | 说明 |
---|---|---|
crashServerUrl | string | 要上报的域名 |
3.1.7 设置上传日志路径
public static void SetLogPath(string logPath);
说明:设置崩溃后上传的日志路径,需要可读权限。在Android和iOS端上,该接口的优先级低于日志路径回调 PS4、PS5、Switch不可用,鸿蒙暂不可用
参数 | 类型 | 说明 |
---|---|---|
logPath | string | 日志绝对路径 |
3.1.8 debug使能开关
public static void ConfigDebugMode(bool enable);
说明:是否开启debug模式,默认为关。开启后会打印一定量的日志,但是可以方便测试期间的问题定位。
备注:需要在InitWithAppId接口之前调用。
参数 | 类型 | 说明 |
---|---|---|
enable | bool | debug使能开关 |
3.1.9 设置设备ID
public static void SetDeviceId(string deviceId);
说明:设置设备ID,默认采用uuid作为设备ID Win、Xbox、PS4、PS5、Switch、鸿蒙暂不可用
备注:需要在InitWithAppId接口之前调用。
参数 | 类型 | 说明 |
---|---|---|
deviceId | string | 设备ID |
3.1.10 设置自定义日志上报级别
public static void ConfigCrashReporter(int logLevel);
说明:设置自定义日志上报级别 Off=0,Error=1,Warn=2,Info=3,Debug=4, 默认Info。
备注:需要在InitWithAppId接口之前调用。
参数 | 类型 | 说明 |
---|---|---|
logLevel | int | 日志级别 |
3.1.11 自定义日志
public static void PrintLog(CSLogSeverity level, string format, params object[] args);
说明:自定义日志,限制30KB
参数 | 类型 | 说明 |
---|---|---|
level | CSLogSeverity | 日志级别 |
format | string | 日志格式 |
args | params object[] | 可变参数 |
自定义日志查看: Android、iOS、PS4、PS5、Switch:问题详情->跟踪日志->custom log Windows、Xbox、Linux:问题详情->自定义日志(来自接口)
3.1.12 设置回调
public static void RegisterCrashCallback(CrashSightCallback callback);
说明: 崩溃时调用,返回值随崩溃信息一起上报 自定义CsCrashCallBack类,继承CrashSightCallback,实现OnCrashBaseRetEvent方法 PS4、PS5、Switch、Linux暂不可用
public class CsCrashCallBack: CrashSightCallback {
// Put you own code to implemente the callback func
public override string OnCrashBaseRetEvent(int methodId)
{
if (methodId == (int)UQMMethodNameID.UQM_CRASH_CALLBACK_EXTRA_MESSAGE)
{
//Android、iOS可返回extraMessage
return "this is extra message.";
}
else if (methodId == (int)UQMMethodNameID.UQM_CRASH_CALLBACK_NO_RET)
{
//Win、Xbox返回值无用,但可执行一些操作
}
return "";
}
}
Android 回调内容在页面“崩溃详情页->附件下载-extraMessage.txt” iOS 回调内容在页面“崩溃详情页->附件下载-crash_attach.log”
PS4、PS5、Switch、Linux、鸿蒙暂不可用
3.2 Android、iOS、Mac端接口
3.2.1 回调开关
public static void ConfigCallbackType(Int32 callbackType);
说明:各类上报的回调开关,目前是5种类型,用5位表示。第一位表示crash,第二位表示anr,第三位表示u3d c# error,第四位表示js,第五位表示lua,默认全开。
参数 | 类型 | 说明 |
---|---|---|
callbackType | Int32 | 回调开关 |