04/29/2024 11:54:53

异常上报模块

一、概述

当游戏发生异常或者崩溃的时候，可以上报异常堆栈信息到渠道管理端上。 支持的渠道有：

1. Bugly
2. Firebase

业务通过 MSDKConfig.ini 文件中配置字段 CRASH_REPORT_ENABLE 和 CRASH_REPORT_CHANNEL 来启用且选择崩溃上报渠道。

若启用且配置了上报渠道，MSDK 在 SDK 内会自动初始化了对应渠道的崩溃上报，业务无需关注初始化。默认是上报的 UserID 是 MSDK openid。

二、接入向导

2.1 打印自定义日志

1）功能描述

自定义日志打印接口，用于记录一些关键的业务调试信息，可以更全面地反映 APP 发生崩溃或异常的上下文环境。

• Bugly 在“跟踪日志”选择“自定义日志”查看
• Firebase 在 Logs 进行日志下载查看

2）接口声明

public static void LogInfo (MSDKCrashLevel level, string tag, string log)

static void LogInfo(int level, const string &tag, const string &log);

3）入参说明

4）示例代码

MSDKCrash.LogInfo (1, "TAG-crash", "LOG-crash");

MSDKCrash::LogInfo(4, "MSDK Crash Tag 4", "MSDK Crash log 4");

5）数据结构

MSDKCrashLevel 日志级别

public enum MSDKCrashLevel
{
	BuglyLogLevelSilent = 0, // 关闭日志记录功能
	BuglyLogLevelError = 1,  
	BuglyLogLevelWarn = 2,
	BuglyLogLevelInfo = 3,
	BuglyLogLevelDebug = 4,
	BuglyLogLevelVerbose = 5,
}

2.2 设置关键数据，随崩溃信息上报

1）功能描述

设置关键数据键值对，随崩溃信息上报。Bulgy 最多允许设置 9 对键值。

• Bulgy 在“跟踪数据>附件信息”的valueMapOther.txt中查看。
• Firebase 在 Keys 中查看

2）接口声明

public static void SetUserValue (string key, string value)

public static void SetUserValue(const string &key, const string &value)

3）入参说明

4）示例代码

MSDKCrash.SetUserValue ("DataKey", "Data Value");

MSDKCrash::SetUserValue("MSDKCrashKey", "MSDK Crash Value");

2.3 设置用户ID

1）功能描述

支持自定义设置用户 ID，您可能会希望能精确定位到某个用户的异常，通过该接口记录用户 ID，在页面上可以精确定位到每个用户发生 Crash 的情况。默认上报的用户 ID 是 MSDK openid。Bugly 和 Firebase 都支持。

2）接口声明

public static void SetUserId (string userId)

public static void SetUserId(const string &userId)

3）入参说明

4）示例代码

MSDKCrash.SetUserId ("12345abcd");

MSDKCrash::SetUserId("12345abcd");

2.4 设置崩溃时额外日志/二进制数据上报

1）功能描述

当程序 Crash 时，有时需要添加一些额外的自定义数据/二进制数据，随 Crash 日志一起上报到 Bugly 平台，这样可以更好的定位造成 Crash 的原因。 上传额外日志/二进制数据，上报的数据可以在 Bugly 平台上的“跟踪数据”->“附件信息”中找到。 这两个文件 Android/iOS 的命名方式不同。且 Bugly 平台设计，Android “附件信息”中默认比 iOS 多一个二进制文件。

2）接口声明

public string OnCrashBaseRetEvent(MSDKBaseRet baseRet)

const char* OnCrashExtraMessageNotify() {

};

long OnCrashExtraDataNotify(MSDKCrashRet &crashRet){

};

3）回调说明

注意，回调返回的数据不能超过30K。且 Bugly 平台设计，iOS 只有应用 Crash 时才会触发此回调，Android 中自定义异常上报和应用 Crash 都会触发此回调。

• Unity

1、在调用 MSDK.Init (); 的时候，手动设置回调 MSDKCrash.SetCrashCallback();
2、在代码中增加回调 MSDKCrash.CrashBaseRetEvent += OnCrashBaseRetEvent; 在回调中处理额外数据。
3、根据回调的 MSDKBaseRet.MethodNameId 来判断本次回调类型。接口 return 的 string 为需要回调返回的数据。

MSDK_CRASH_CALLBACK_EXTRA_MESSAGE 对应的是额外日志
MSDK_CRASH_CALLBACK_EXTRA_DATA 对应的是额外二进制数据

二进制数据也需要转换成 string。

• UnrealEngine

需继承MSDKCrashObserver，实现回调两个方法：

OnCrashExtraMessageNotify 对应的是额外日志

OnCrashExtraDataNotify 对应的是额外二进制数据

4）示例代码

MSDKCrash.SetCrashCallback();
MSDKCrash.CrashBaseRetEvent += OnCrashBaseRetEvent;

public string OnCrashBaseRetEvent(MSDKBaseRet baseRet)
{
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_CRASH_CALLBACK_EXTRA_DATA)
    {
// 这里是非unity进程，注意不要做unity相关的操作
        return "this is extra data.";
    }
    else if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_CRASH_CALLBACK_EXTRA_MESSAGE)
    {
       // 这里是非unity进程，注意不要做unity相关的操作
       return "this is extra message.";
    }
    return "";
}

//销毁的时候需要移除监听
private void OnDestroy()
{
    MSDKCrash.CrashBaseRetEvent -= OnCrashBaseRetEvent;
}

class CrashObserver : public MSDKCrashObserver {
public:
    const char* OnCrashExtraMessageNotify() {
        char str1[]= "this is extra message.";
        char *retValue = SAFE_MALLOC(strlen(str1) + 1, char);
        strcpy(retValue, str1);
        return retValue;
    };

    long OnCrashExtraDataNotify(MSDKCrashRet &crashRet){
        char str[]= "this is extra data.";
        crashRet.data = SAFE_MALLOC(strlen(str) + 1, char);
        strcpy(crashRet.data, str);
        return strlen(crashRet.data);
    };
};

MSDKCrash::SetCrashObserver(new CrashObserver());

2.5 设置自动上报的等级（仅支持 Unity）

1）功能描述

自主设置日志上报的等级。比如 Bugly Unity 默认 LogError 和 Exception 等级会上报，如果用户不希望 LogError 等级也上报，可以通过该接口进行设置。

2）接口声明

public static void SetAutoReportLogLevel(int level)

3）入参说明

4）示例代码

MSDKCrash.SetAutoReportLogLevel(0);

2.6 设置 MSDK 的上报异常堆栈

1）功能描述

通过 MSDK（Bugly）上报 App 异常堆栈，例如：c#，Lua等。

2）接口声明

public static void ReportException(int type, string exceptionName, string exceptionMsg, string exceptionStack, Dictionary<string, string> extInfo)

static void ReportException(int type, const String &exceptionName, const String &exceptionMsg, const String &exceptionStack, std::map<std::string, std::string> &extInfo)

3）入参说明

4）示例代码

Dictionary<string, string> extraInfo = new Dictionary<string, string>();
extraInfo.Add("k1", "v1");
extraInfo.Add("k2", "v2");
extraInfo.Add("k3", "v3");
MSDKCrash.ReportException(6,"NexceptionNameame","exceptionMsg","exceptionStack",extraInfo);

std::map<std::string, std::string> extraInfo;
extraInfo["k1"] = "v1";
extraInfo["k2"] = "v2";
extraInfo["k3"] = "v3";
MSDKCrash::ReportException(6, "exceptionName", "exceptionMsg", "exceptionStack", extraInfo);

2.7 动态关闭Crash上报 (当前仅Bugly渠道支持)

1）功能描述

1. 有些场景下，应用不需要崩溃上报，如：有些应用在杀进程时触发的上报不想上报到bugly；此时可以调用该接口关闭崩溃上报，其他bugly功能不影响；重新启动应用后再触发的崩溃会正常上报
2. 动态关闭bugly上报。调用时会关闭崩溃上报，其他bugly功能不影响；重新启动应用后再触发的崩溃会正常上报。

2）接口声明

public static void CloseCrashReport()

static void CloseCrashReport()

3）示例代码

MSDKCrash.CloseCrashReport();

MSDKCrash::CloseCrashReport();