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.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: https://harmony.crashsight.qq.com
- Windows: pc.crashsight.qq.com
- Mac: https://mac.crashsight.qq.com/pb/sync
- PS5: https://ps5.crashsight.qq.com/pb/async
- Xbox: xbox.crashsight.qq.com
海外公有云
- Android: https://android.crashsight.wetest.net/pb/async
- iOS: https://ios.crashsight.wetest.net/pb/sync
- Harmony: https://harmony.crashsight.wetest.net
- Windows: pc.crashsight.wetest.net
- Mac: https://mac.crashsight.wetest.net/pb/sync
- PS5: https://console.crashsight.wetest.net/pb/async
- Xbox: xbox.crashsight.wetest.net
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);
#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)
仅在 C# 中调用 CrashSightAgent.InitWithAppId 时，初始化发生在 Unity 引擎与脚本环境就绪之后。应用进程更早阶段（例如 Android Application/Activity 创建、iOS main/AppController 启动）若已发生 Native 崩溃或信号异常，可能无法被捕获。
因此 Android / iOS 支持在系统原生层提前初始化 CrashSight：与第 1 章相同，先将 Unity Plugin 导入工程；Plugin 内已带上 Android / iOS 原生库。导出工程后这些库会进入宿主原生工程，可直接在 Java / Objective-C / C++ 中调用初始化接口，无需再单独接入一份 Mobile SDK。
导出后的典型关系如下：
| 端 | Plugin 中的位置（导入 Unity 工程后） | 导出后进入的宿主工程 | 原生侧可直接使用的能力 |
|---|---|---|---|
| Android | Assets/Plugins/Android/CrashSight/（含 CrashSight 相关 jar/aar、libCrashSight.so、Manifest 合并配置等） | Gradle 工程中的 unityLibrary（libs / jniLibs 等目录会带上上述产物） | import com.uqm.crashsight.core.api.crash.UQMCrash，System.loadLibrary("CrashSight") 后调用配置与 initWithAppId |
| iOS | Assets/Plugins/iOS/CrashSight/（含 CrashSight.framework / CrashSightCore.framework / CrashSightPlugin.framework / CrashSightAdapter.framework 等） | 导出的 Xcode 工程并已链接上述 framework | #include CrashSightMobileAgent.h 等头文件，调用 GCloud::CrashSight::CrashSightMobileAgent::... |
说明：
- 不同版本 Plugin 的目录细节可能略有差异，以实际下载包为准；关键是导出后宿主工程里已经链接 CrashSight 原生库，因此可在原生启动路径上调用。
- 原生层完成初始化后，Android 还必须在 C# 侧做一次重注册，见 2.3；iOS 一般无需重注册。
2.1 下载并导入Unity Plugin到Unity项目工程
在平台成功创建项目后，在侧边栏的「接入指南」中下载与项目平台、引擎匹配的 SDK，并导入 Unity 工程（与第 1 章相同）。如下图所示：
导入成功后，确认工程中存在 Assets/CrashSight（C# 脚本）以及上表中的 Assets/Plugins/Android|iOS/CrashSight 原生产物，再执行 Android / iOS 导出。
2.2 SDK初始化
在导出后的宿主工程中，于尽可能早的原生启动路径调用初始化（例如 Android 自定义 Application 或 UnityPlayerActivity.onCreate 靠前位置；iOS AppController / 等价启动入口）。以下为参考代码（域名、AppID 请按项目环境替换；国内公有云示例如下）。
Android（unityLibrary 内 Java，接口类 UQMCrash）：
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/pb/async");//这是国内的上报域名
UQMCrash.initWithAppId("******");
iOS（Xcode 工程内，接口类 CrashSightMobileAgent）：
#include "CrashSight/CrashSightCore.framework/Headers/CrashSightMobileAgent.h"
...
// 先写入配置信息，此处只是示例，具体配置接口可参考 CrashSightMobileAgent.h
GCloud::CrashSight::CrashSightMobileAgent::ConfigDebugMode(true);//开启debug
GCloud::CrashSight::CrashSightMobileAgent::SetUserId("testUserId");//设置用户ID
GCloud::CrashSight::CrashSightMobileAgent::SetAppVersion("testVersion");//设置版本
// 再进行初始化
GCloud::CrashSight::CrashSightMobileAgent::ConfigCrashServerUrl("https://ios.crashsight.qq.com/pb/sync");//这是国内的上报域名
GCloud::CrashSight::CrashSightMobileAgent::InitWithAppId("******");
2.3 安卓重注册
由于 Unity 5 以后的兼容性问题，在原生层完成初始化后，Android 必须在 C# 层再调用一次重注册；iOS 暂时无需操作。
重注册接口：
CrashSightAgent.ReRegistAllMonitors();
请在 C# 脚本中尽可能早的位置调用（例如首个 Scene 加载后、其它 CrashSight C# 逻辑之前）。未重注册时，可能出现原生已初始化但引擎侧监控/回调未正确挂接的情况。
2.4 注册 C# 异常与 Log 捕获（可选）
在原生层已完成初始化、且未在 C# 调用 CrashSightAgent.InitWithAppId 时，可调用：
CrashSightAgent.EnableExceptionHandler();
该接口会在 Unity 侧注册两类捕获（内部调用 _RegisterExceptionHandler）：
- Unity Log 回调：通过
Application.logMessageReceived/logMessageReceivedThreaded监听日志；可将 Unity Log Error 等作为错误上报到 CrashSight。 - 未处理异常：通过
AppDomain.CurrentDomain.UnhandledException捕获未处理的 C# 异常并上报。
说明：
- 适用场景：第 2 章这种「原生提前初始化」、C# 侧不再走
InitWithAppId的接入方式。若已调用InitWithAppId，初始化流程内已包含同等注册，一般无需再调本接口。 - 调用顺序：请在
ReRegistAllMonitors之前调用。ReRegistAllMonitors会将 SDK 标记为已初始化；若先重注册再调EnableExceptionHandler，接口会直接返回，不会补注册上述 Log / UnhandledException 回调。 - 开启 Log 捕获后，请尽量控制项目中 Unity Log Error 的触发频率，避免过量上报。
3 C#接口说明
全平台接口是指所有平台都通用的接口，覆盖了CrashSight的大部分基础功能，如：初始化、错误上报等。此外，每个平台可能会有一些独有的接口，会在后文单独列出。一个平台上可以使用的全部接口为：全平台接口+该平台独有的接口。
3.1 全平台接口
3.1.1 初始化
public static void InitWithAppId(string appId, bool forceOnUiThread = false);
说明： 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。 appid是CrashSight对项目的唯一标识，可以在产品设置->产品信息中查看。
| 参数 | 类型 | 说明 |
|---|---|---|
| appId | string | 已注册项目的 APP ID |
| forceOnUiThread | bool | 可选。为 true 时强制在 UI 线程执行初始化相关逻辑，默认 false；仅影响 Android |
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；支持自定义错误类型 21 ~ 30 |
| exceptionName | string | 异常名称 |
| exceptionMsg | string | 异常信息 |
| exceptionStack | string | 堆栈 |
| extInfo | Dictionary<string, string> | 其他信息（键值对） |
| dumpNativeType | int | 0：关闭；1：调用系统接口 dump（Android、iOS）；3：minidump（Android、iOS）；4：全线程堆栈（仅 Android）。Win/主机等平台该参数可能被忽略 |
| errorAttachmentPath | string | 日志附件的绝对路径（Android、iOS、Windows 有效） |
注：dumpNativeType 为 0 时错误异步上报，非 0 时为同步上报。推荐仅在卡死或严重错误时开启以获取额外信息。鸿蒙请使用不含 extInfo/dumpNativeType 的重载或其它上报路径。
页面查看：
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}；Mac、鸿蒙由 SDK 从包信息自动读取。以上平台无需在初始化前调用本接口。
Windows、Linux、PS5、Switch、Xbox 等平台须在 InitWithAppId 之前调用。
| 参数 | 类型 | 说明 |
|---|---|---|
| appVersion | string | 版本号 |
3.1.6 上报域名设置
public static void ConfigCrashServerUrl(string crashServerUrl);
说明：设置上报域名。
备注：需要在InitWithAppId接口之前调用。
各端国内/海外公有云域名见上文 1.2 初始化 中的完整列表。
直接接入 CrashSight 域名与 MSDK 转接不同，请务必按对应端域名配置。其他环境域名请咨询接入接口人。
| 参数 | 类型 | 说明 |
|---|---|---|
| crashServerUrl | string | 要上报的域名 |
3.1.7 设置上传日志路径
public static void SetLogPath(string logPath);
说明：设置崩溃后上传的日志路径，需要可读权限。在 Android 和 iOS 端上，该接口的优先级低于日志路径回调。
平台：Android、iOS、Mac、鸿蒙、Windows、Xbox、PS4、PS5、Linux 可用；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。
平台：Android、iOS、Mac、鸿蒙、Windows、Xbox、PS4、PS5、Switch、Linux 均可用。
备注：需要在 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、Mac、PS4、PS5、Switch：问题详情->跟踪日志->custom log Windows、Xbox、Linux：问题详情->自定义日志（来自接口）
3.1.12 设置回调
public static void RegisterCrashCallback(CrashSightCallback callback);
说明：
错误、崩溃时调用，返回值随错误和崩溃信息一起上报。自定义 CsCrashCallBack 类，继承 CrashSightCallback，实现 OnCrashBaseRetEvent(int methodId, int crashType) 方法。
平台：Android、iOS、Mac、Windows、Xbox 可用；PS4、PS5、Switch、Linux、鸿蒙暂不可用。
public class CsCrashCallBack: CrashSightCallback {
// Put your own code to implement the callback
public override string OnCrashBaseRetEvent(int methodId, int crashType)
{
if (methodId == (int)UQMMethodNameID.UQM_CRASH_CALLBACK_EXTRA_MESSAGE)
{
// Android、iOS、Mac 可返回 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」
3.1.13 上报轻量级日志
public static void ReportLogInfo(string msgType, string msg);
说明：上报轻量级日志。
平台：仅 Android、iOS、Mac、鸿蒙、Linux 可用。
| 参数 | 类型 | 说明 |
|---|---|---|
| msgType | string | 日志类型 |
| msg | string | 日志内容 |
3.1.14 标记场景
public static void SetScene(string sceneId, bool upload = false);
public static void SetScene(int sceneId, bool upload = false);
说明：
设置场景 ID。每一个联网或者上报都可以携带该字段，实现针对不同子场景计算崩溃率等数据。upload 为 true 时会上报场景变更。
平台：仅 Android、iOS、Mac、鸿蒙 可用。
| 参数 | 类型 | 说明 |
|---|---|---|
| sceneId | string / int | 场景 ID |
| upload | bool | 是否上报场景变更，默认 false |
3.1.15 设置发行渠道
public static void SetEnvironmentName(string serverEnv);
说明： 设置发行渠道。每一个联网或者上报都可以携带该字段，可实 现针对不同发行渠道统计数据。
平台：仅 Android、iOS、Mac、Windows、Xbox 可用；PS4、PS5、Switch、Linux、鸿蒙暂不可用。
| 参数 | 类型 | 说明 |
|---|---|---|
| serverEnv | string | 发行渠道名称 |
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 | 回调开关 |
3.2.2 设置Android手机型号
public static void SetDeviceModel(string deviceModel);
说明：设置手机型号
备注：需要在InitWithAppId接口之前调用。
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceModel | string | 手机型号 |
3.2.3 获取崩溃线程ID
public static long GetCrashThreadId();
说明： 当崩溃发生时，获取崩溃线程ID，失败时返回-1，可在回调中调用
3.2.4 设置自定义device ID
public static void SetCustomizedDeviceID(string deviceId);
说明： 设置自定义device ID
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceId | string | 自定义device ID |
3.2.5 获取SDK生成的device ID
public static string GetSDKDefinedDeviceID();
说明： 获取SDK生成的device ID
3.2.6 设置自定义match ID
public static void SetCustomizedMatchID(string matchId);
说明： 设置自定义match ID，match id可用于在“高级搜索”中查找崩溃和错误
| 参数 | 类型 | 说明 |
|---|---|---|
| matchId | string | match ID |
3.2.7 获取SDK生成的session ID
session ID用于唯一标记一次启动，一般用于在回调中确定是否为同一次启动。
public static string GetSDKSessionID();
说明： 获取SDK生成的session ID
3.2.8 获取崩溃UUID
public static string GetCrashUuid();
说明： 获取当次上报的UUID，该UUID用于唯一标识一次上报，一般在回调中使用
3.2.9 设置logcat缓存大小
public static void SetLogcatBufferSize(int size);
说明： 设置 logcat 缓存大小，默认非 debug 模式下 10KB，debug 模 式下 128KB。仅 Android 有效。
| 参数 | 类型 | 说明 |
|---|---|---|
| size | int | logcat 缓存大小 |
3.2.10 启动定时dump
public static void StartDumpRoutine(int dumpMode, int startTimeMode, long startTime, long dumpInterval, int dumpTimes, bool saveLocal, string savePath);
说明： 启动一个线程，定时获取dump并上报。根据dump间隔和dump次数的的设定会产生一定的性能开销，一般用于测试。请在正式发布前关闭该功能。
| 参数 | 类型 | 说明 |
|---|---|---|
| dumpMode | int | dump模式，1：dump，2：minidump |
| startTimeMode | int | 启动时间模式，0：绝对时间，1：相对时间，单位：毫秒ReportException |
| startTime | long | 启动时间 |
| dumpInterval | long | dump间隔，单位：毫秒 |
| dumpTimes | int | dump次数 |
| saveLocal | bool | 是否保存本地 |
| savePath | string | 本地保存路径 |
3.2.11 获取异常类型编号
public static int getExceptionType(string name);
说明： 根据异常名的字符串获取异常类型编号，可用于填写ReportException接口的type参数
| 参数 | 类型 | 说明 |
|---|---|---|
| name | string | 异常类型名，如“c#”、“js”、“lua”、“custom1”等 |
3.2.12 重启CrashSight监控
public static void ReRegistAllMonitors();
说明： 重启CrashSight监控，通常在原生接入时使用 仅Android有效
3.2.13 关闭CrashSight监控
public static void CloseAllMonitors();
说明： 关闭CrashSight监控 Android、iOS: 自SDK 4.2.15版本开始支持; MAC: 自SDK 4.3.6版本开始支持
3.2.14 设置上传日志回调
public static void RegisterCrashLogCallback(CrashSightLogCallback callback);
说明： 崩溃处理后调用，自定义CsCrashLogCallback类，继承CrashSightLogCallback，实现OnSetLogPathEvent、OnLogUploadResultEvent方法
文件大小默认压缩前不超过20MB，压缩后不超过10MB（上传过程中会对数据进行压缩），可通过云控更改默认限制。
public class CsCrashLogCallBack : CrashSightLogCallback
{
// 返回日志文件的绝对路径
// methodId 方法ID，业务侧忽略
// crashType 崩溃类型，0：java/oc崩溃，2：native崩溃
public override string OnSetLogPathEvent(int methodId, int crashType)
{
return "";
}
// 通知日志文件的上传结果
// methodId 方法ID，业务侧忽略
// result 上传结果 0：成功，其他：失败
public override void OnLogUploadResultEvent(int methodId, int crashType, int result)
{
}
}
Android 回调内容在页面“崩溃详情页->附件下载-客户端上传日志” iOS 回调内容在页面“崩溃详情页->附件下载-客户端上传日志”
3.2.15 上报卡顿
public static void ReportJank(int type, string exceptionName, string exceptionMsg, string exceptionStack, string paramsJson, int reportInfoOption, string jankAttachmentPath);
说明：主动上报卡顿（Android、iOS；鸿蒙桥接亦有实现）。type 为异常类型（与 ReportException 的 type 相同）。
| 参数 | 类型 | 说明 |
|---|---|---|
| type | int | 异常类型（同 ReportException） |
| exceptionName | string | 异常名称 |
| exceptionMsg | string | 异常信息 |
| exceptionStack | string | 堆栈 |
| paramsJson | string | 额外信息的 JSON 字符串 |
| reportInfoOption | int | Android 为 6 位标志（第 6 位为全线程 Java 堆栈）；iOS 为 5 位 CSExceptionReprotOption（无第 6 位），详见 mobile-sdk |
| jankAttachmentPath | string | 附件路径，可传空 |
3.2.16 上报卡死
public static void ReportStuck(int threadId, int maxChecks, long checkInterval, string name, string message, Dictionary<string, string> extInfo, int dumpNativeType, string attachPath);
说明：上报线程卡死类异常（Android、iOS；Win/Xbox/鸿蒙桥接亦 有实现）。
| 参数 | 类型 | 说明 |
|---|---|---|
| threadId | int | 目标线程 ID |
| maxChecks | int | 最大检测次数 |
| checkInterval | long | 检测间隔（毫秒） |
| name | string | 异常名称 |
| message | string | 异常信息 |
| extInfo | Dictionary<string, string> | 额外信息，插件层序列化为 JSON |
| dumpNativeType | int | 0 关闭，1 系统 dump，3 minidump |
| attachPath | string | 附件路径，可传空 |
3.2.17 内存接近上限回调
public static void SetMemoryNearLimitCallback(ulong memoryThresholdBytes, long memoryLimitBytes, double timeIntervalSeconds, Action<ulong, ulong> callback);
说明：当 footprint 接近 iOS 内存上限时触发回调。仅 iOS / Mac 且 OOM 监控开启时生效。
内存上限可由 memoryLimitBytes 指定：传 -1 使用系统采集值（footprint + os_proc_available_memory()，仅 iOS 13+）；传 >= 0 则直接使用该值作为上限。
| 参数 | 类型 | 说明 |
|---|---|---|
| memoryThresholdBytes | ulong | footprint 距上限的阈值（字节）。当 (memoryLimit - footprint) < 该阈值 时触发回调 |
| memoryLimitBytes | long | 内存上限（字节）。-1：用系统采集上限；>= 0：用传入值 |
| timeIntervalSeconds | double | 两次回调的最小间隔（秒）。0 表示仅触发一次 |
| callback | Action<ulong, ulong> | 回调。参数依次为当前 footprint、memoryLimit。传 null 取消注册 |
用法示例：
// 使用系统采集的内存上限
CrashSightAgent.SetMemoryNearLimitCallback(
50UL * 1024 * 1024, // 距上限 50MB 内触发
-1L, // -1：采集上限
5.0, // 最少间隔 5 秒
(footprint, memoryLimit) =>
{
// 处理接近上限逻辑；勿在回调中执行耗时或可能二次崩溃的操作
});
// 使用自定义内存上限（例如 1.5GB）
CrashSightAgent.SetMemoryNearLimitCallback(
100UL * 1024 * 1024,
1610612736L,
1.0,
(footprint, memoryLimit) => { /* ... */ });
// 取消注册
CrashSightAgent.SetMemoryNearLimitCallback(0, -1L, 0, null);
3.3 PC、Xbox端接口
3.3.1 启用Veh异常处理
public static void SetVehEnable(bool enable);
说明：VEH捕获开关，默认开。建议所有Unity项目关闭此开关，否则可能产生crash误报。
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | Veh异常处理开关 |
3.3.2 主动上报崩溃
public static void ReportCrash();
说明：主动上报一条崩溃信息。一般没有使用场景，可根据项目需要酌情使用。
3.3.3 主动上报dump
public static void ReportDump(string dump_path, bool is_async);
说明：主动上报Dump。一般没有使用场景，可根据项目需要酌情使用。
| 参数 | 类型 | 说明 |
|---|---|---|
| dump_path | string | dump目录 |
| is_async | bool | 是否异步 |
3.3.4 开启额外异常捕获
public static void SetExtraHandler(bool extra_handle_enable);
说明：设置额外的异常处理机制，默认为关闭，与旧版保持一致。 开启后，可以捕获上报strcpy_s一类的安全函数抛出的非法参数崩溃，以及，虚函数调用purecall错误导致的崩溃。
| 参数 | 类型 | 说明 |
|---|---|---|
| extra_handle_enable | bool | 额外异常捕获开关 |
3.3.5 上传dump文件
public static void UploadGivenPathDump(string dump_dir, bool is_extra_check);
说明：上传指定路径下的dump文件
| 参数 | 类型 | 说明 |
|---|---|---|
| dump_dir | string | dump文件地址 |
| is_extra_check | bool | 默认填false即可 |
3.3.6 设置崩溃上报开关
public static void SetCrashUploadEnable(bool enable);
说明：设置是否上报崩溃，默认为开启。
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | 崩溃上报开关 |
3.4 PS4、PS5、Switch端接口
3.4.1 设置错误上报间隔
public static void SetErrorUploadInterval(int interval);
说明：设置错误上报间隔，默认30s
| 参数 | 类型 | 说明 |
|---|---|---|
| interval | int | 错误上报间隔 |
3.4.2 错误上报开关
public static void SetErrorUploadEnable(bool enable);
说明：是否开启错误上报，默认开启
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | 错误上报开关 |
3.5 Linux端接口
3.5.1 设置所有记录文件的路径
public static void SetRecordFileDir(string record_dir);
说明：设置所有记录文件的路径，包括SDK日志和dump文件，默认为当前可执行文件的目录下。
| 参数 | 类型 | 说明 |
|---|---|---|
| record_dir | string | 记录文件路径 |