• 1 Unity引擎C#接入方案
  • 2 系统原生层接入Unity引擎方案(Android&iOS)
  • 3 C#接口说明

Unity SDK开发接入


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

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

本文档适用于最新版本,Xbox、PS4、PS5、Switch及Linux平台可参考本文档接入。Android、iOS及Windows平台接入建议参考稳定版本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.ConfigDebugMode (false);

// 设置上报的目标域名,请根据项目需求进行填写。(必填)
        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
  • Windows: pc.crashsight.qq.com

海外公有云

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

1.3 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栏目下添加如下依赖性:
    • i. libz.dylib 用于对上报的数据进行压缩
    • ii. Security.framework 用于存储keychain
    • iii. SystemConfiguratiom.framework 用于读取异常发生时的系统信息
    • iiii. MetricKit.framework 用于获取apple提供的app诊断信息

注意:

  • i. 如果项目已经添加过这些依赖项,不用重复添加。
  • ii. 通过XUPorter集成无需在Xcode中添加配置。

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
  • 3)iOS接入与安卓类似,不过需要将项目打包为xcode项目,然后在xcode项目中进行配置。Windows需要修改GameBabyConfig64.dat中的配置信息。

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后,联网上报是否正常,具体验证方法如下:

    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.错误上报的版本号,用户名是否与设置一致.

1.6 上传符号表

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

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 发生崩溃/错误时的回调。(可选)

如果项目想在发生崩溃/错误时,在上报信息中加入一些内容,可以通过处理回调加入相关内容。 需要注意的是:

    1. 回调中的处理请尽可能保证线程安全,防止二次崩溃的发生。发生二次崩溃后,当前崩溃无法在本次完成上报,条件允许的情况下,下次启动会进行上报,但是不会包含回调内容。
    1. 回调的信息请遵守合规要求。

3 C#接口说明

3.1 全平台接口

3.1.1 初始化

public static void InitWithAppId(string appId);

说明: 执行初始化工作。 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能。
appid是CrashSight对项目的唯一标识,可以在产品设置->产品信息中查看。
Win、Xbox、Linux暂不可用

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

3.1.2 上报错误

public static void ReportException(System.Exception e, string message);

说明: 主动上报错误信息,用于上报捕获的c#异常。

参数类型说明
eSystem.Exception捕获到的异常
messagestring异常信息
public static void ReportException(string name, string message, string stackTrace);

说明: 主动上报错误信息。可以在捕获到错误或者需要上报的时候手动调用,支持多线程调用。
name、message和stackTrace不能为null。

参数类型说明
namestring异常名称
messagestring异常信息
stackTracestring堆栈
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。

参数类型说明
typeint异常类型, C#: 4, js: 5, lua: 6
exceptionNamestring异常名称
exceptionMsgstring异常信息
exceptionStackstring堆栈
extInfoDictionary<string, string>其他信息
dump_native_typeint0:关闭,1:调用系统接口dump,3:minidump(仅移动端有效)
errorAttachmentPathstring日志附件的绝对路径(仅Android有效)

页面查看:

extras:崩溃详情页->附件下载->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.1.3 设置用户ID

public static void SetUserId(string userId);

说明: 设置用户ID。用户id默认为unknown。

参数类型说明
userIdstring用户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

参数类型说明
keystring
valuestring

3.1.5 设置应用版本

public static void SetAppVersion(string appVersion);

说明:设置应用版本号

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

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

Win、Xbox暂不可用

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

参数类型说明
appVersionstring版本号

3.1.6 上报域名设置

public static void ConfigCrashServerUrl(string crashServerUrl);

说明:设置上报域名。
Win、Xbox暂不可用

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

国内公有环境域名如下:

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

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

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

参数类型说明
crashServerUrlstring要上报的域名

3.1.7 设置上传日志路径

public static void SetLogPath(string logPath);

说明:设置崩溃后上传的日志路径,需要可读权限。在Android和iOS端上,该接口的优先级低于日志路径回调
Switch不可用

参数类型说明
logPathstring日志绝对路径

3.1.8 debug使能开关

public static void ConfigDebugMode(bool enable);

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

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

参数类型说明
enablebooldebug使能开关

3.1.9 设置设备ID

public static void SetDeviceId(string deviceId);

说明:设置设备ID,默认采用uuid作为设备ID
Win、Xbox、PS4、PS5、Switch暂不可用

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

参数类型说明
deviceIdstring设备ID

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

public static void ConfigCrashReporter(int logLevel);

说明:设置自定义日志上报级别 Off=0,Error=1,Warn=2,Info=3,Debug=4, 默认Warn。
Win、Xbox、PS4、PS5、Switch、Linux暂不可用

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

参数类型说明
logLevelint日志级别

3.1.11 自定义日志

public static void PrintLog(CSLogSeverity level, string format, params object[] args);

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

参数类型说明
levelCSLogSeverity日志级别
formatstring日志格式
argsparams 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”

3.2 移动端接口

3.2.1 回调开关

public static void ConfigCallbackType(Int32 callbackType);

说明:各类上报的回调开关,目前是5种类型,用5位表示。第一位表示crash,第二位表示anr,第三位表示u3d c# error,第四位表示js,第五位表示lua,默认全开。

参数类型说明
callbackTypeInt32回调开关

3.2.2 设置Android手机型号

public static void SetDeviceModel(string deviceModel);

说明:设置手机型号

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

参数类型说明
deviceModelstring手机型号

3.2.3 上报轻量级日志

public static void ReportLogInfo(string msgType, string msg);

说明:上报轻量级日志

参数类型说明
msgTypestring日志类型
msgstring日志内容

3.2.4 标记场景

public static void SetScene(int sceneId);

说明: 设置场景ID

参数类型说明
sceneIdint场景ID

3.2.5 获取崩溃线程ID

public static long GetCrashThreadId();

说明: 当崩溃发生时,获取崩溃线程ID,失败时返回-1,可在回调中调用

3.2.6 设置自定义device ID

public static void SetCustomizedDeviceID(string deviceId);

说明: 设置自定义device ID

参数类型说明
deviceIdstring自定义device ID

3.2.7 获取SDK生成的device ID

public static string GetSDKDefinedDeviceID();

说明: 获取SDK生成的device ID

3.2.8 设置自定义match ID

public static void SetCustomizedMatchID(string matchId);

说明: 设置自定义match ID,match id可用于在“高级搜索”中查找崩溃和错误

参数类型说明
matchIdstringmatch ID

3.2.9 获取SDK生成的session ID,session ID用于唯一标记一次启动,一般用于在回调中确定是否为同一次启动。

public static string GetSDKSessionID();

说明: 获取SDK生成的session ID

3.2.10 获取崩溃UUID

public static string GetCrashUuid();

说明: 获取当次上报的UUID,该UUID用于唯一标识一次上报,一般在回调中使用

3.2.11 设置logcat缓存大小

public static void SetLogcatBufferSize(int size);

说明: 设置logcat缓存大小,默认非debug模式下10KB,debug模式下128KB

参数类型说明
sizeintlogcat缓存大小

3.2.12 启动定时dump

public static void StartDumpRoutine(int dumpMode, int startTimeMode, long startTime, long dumpInterval, int dumpTimes, bool saveLocal, string savePath);

说明: 启动一个线程,定时获取dump并上报。根据dump间隔和dump次数的的设定会产生一定的性能开销,一般用于测试。请在正式发布前关闭该功能。

参数类型说明
dumpModeintdump模式,1:dump,2:minidump
startTimeModeint启动时间模式,0:绝对时间,1:相对时间,单位:毫秒ReportException
startTimelong启动时间
dumpIntervallongdump间隔,单位:毫秒
dumpTimesintdump次数
saveLocalbool是否保存本地
savePathstring本地保存路径

3.2.13 获取异常类型编号

public static int getExceptionType(string name);

说明: 根据异常名的字符串获取异常类型编号,可用于填写ReportException接口的type参数

参数类型说明
namestring异常类型名,如“c#”、“js”、“lua”、“custom1”等

3.2.14 重启CrashSight监控

public static void ReRegistAllMonitors();

说明: 重启CrashSight监控,通常在原生接入时使用
仅Android有效

3.2.15 关闭CrashSight监控

public static void CloseAllMonitors();

说明: 关闭CrashSight监控
仅Android有效

3.2.16 设置上传日志回调

public static void RegisterCrashLogCallback(CrashSightLogCallback callback);

说明: 崩溃处理后调用,自定义CsCrashLogCallback类,继承CrashSightLogCallback,实现OnSetLogPathEvent、OnLogUploadResultEvent方法

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.3 PC、Xbox端接口

3.3.1 启用Veh异常处理

public static void SetVehEnable(bool enable);

说明:VEH捕获开关,默认开。建议所有Unity项目关闭此开关,否则可能产生crash误报。

参数类型说明
enableboolVeh异常处理开关

3.3.2 主动上报崩溃

public static void ReportCrash();

说明:主动上报一条崩溃信息。一般没有使用场景,可根据项目需要酌情使用。

3.3.3 主动上报dump

public static void ReportDump(string dump_path, bool is_async);

说明:主动上报Dump。一般没有使用场景,可根据项目需要酌情使用。

参数类型说明
dump_pathstringdump目录
is_asyncbool是否强制退出程序

3.3.4 开启额外异常捕获

public static void SetExtraHandler(bool extra_handle_enable);

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

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

3.3.5 上传dump文件

public static void UploadGivenPathDump(string dump_dir, bool is_extra_check);

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

参数类型说明
dump_dirstringdump文件地址
is_extra_checkbool默认填false即可

3.4 PS4、PS5、Switch端接口

3.4.1 设置错误上报间隔

public static void SetErrorUploadInterval(int interval);

说明:设置错误上报间隔,默认30s

参数类型说明
intervalint错误上报间隔

3.4.2 错误上报开关

public static void SetErrorUploadEnable(bool enable);

说明:是否开启错误上报,默认开启

参数类型说明
enablebool错误上报开关

3.5 Linux端接口

3.5.1 设置所有记录文件的路径

public static void SetRecordFileDir(string record_dir);

说明:设置所有记录文件的路径,包括SDK日志和dump文件,默认为当前可执行文件的目录下。

参数类型说明
record_dirstring记录文件路径
Last Updated: