05/15/2024 15:19:45

Exception Reporting Module

I. Overview

When a game has an exception or crash, it can report the exception stack information to the channel management system.
Supported channels are:

1. Bugly
2. Firebase

The game can enable and select the crash reporting channel through the configuration fields, CRASH_REPORT_ENABLE andCRASH_REPORT_CHANNEL, in the MSDKConfig.ini file.

If the reporting channel is enabled and configured, MSDK will automatically initialize the crash reporting of the corresponding channel in SDK. Games do not need to pay attention to the initialization. By default, the reported UserID is MSDK openid.

II. Guide on how to access the module

2.1 Print user-defined logs

1) Functional description

The user-defined log printing interface is used to record some key business debugging information. It can more fully reflect the context in which APP has a crash or an exception.

• Bugly - Select "User-defined Log" in "Tracking Log" to view the log
• Firebase - Download the log in Logs to view the log

2) Interface declaration

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

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

3) Description of input parameters

4) Demo code

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

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

5) Data structure

MSDKCrashLevel: log level

public enum MSDKCrashLevel		
{		
	BuglyLogLevelSilent=0, // Disable the logging function	
	BuglyLogLevelError = 1,  	
	BuglyLogLevelWarn = 2,	
	BuglyLogLevelInfo = 3,	
	BuglyLogLevelDebug = 4,	
	BuglyLogLevelVerbose = 5,	
}

2.2 Set Critical Data to Be Reported with Crash Information

1) Functional description

Set critical data key-value pairs to be reported with the crash information. It is allowed to set up to 9 key-value pairs.

• Bulgy - View the data in the valueMapOther.txt file of "Track Data >Attached Information"。
• Firebase - View the data in Keys

2) Interface declaration

public static void SetUserValue (string key, string value)

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

3) Description of input parameters

4) Demo code

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

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

2.3 Set the user ID

1) Functional description

Support setting the user ID by the user himself. You may wish to be able to pinpoint the exception occurring to a user. You can record the user's ID through this interface and can pinpoint the crash occurring to each user on the page. By default, the reporting user ID is MSDK openid. Bugly and Firebase both support this.

2) Interface declaration

public static void SetUserId (string userId)

public static void SetUserId(const string &userId)

3) Description of input parameters

4) Demo code

MSDKCrash.SetUserId ("12345abcd");

MSDKCrash::SetUserId("12345abcd");

2.4 Set up additional log/binary data reporting in the event of a crash

1) Functional description

When the program crashes, it is sometimes necessary to add some additional user-defined data/binary data to be reported to the Bugly platform along with the crash log. This can better locate the cause of the crash.
Upload additional log/binary data. The reported data can be found in "Tracking Data"->"Attachment Information" on the Bugly platform.
The two files are named differently by Android and iOS. And according to the Bugly platform's design, there is one more binary file in "Attachment Information" on Android than on iOS by default.

2) Interface declaration

public string OnCrashBaseRetEvent(MSDKBaseRet baseRet)

const char* OnCrashExtraMessageNotify() {		
		
};		
		
long OnCrashExtraDataNotify(MSDKCrashRet &crashRet){		
		
};

3) Callback description

Note that the data returned by the callback cannot exceed 30K.And the Bugly platform designs that iOS will only trigger this callback when an app crashes. Both user-defined exception reporting and app crash in Android can trigger this callback.

• Unity

• When calling MSDKCrash.Init ();, you can manually set the callback MSDKCrash.SetCrashCallback();
  

• In the code, add the callback MSDKCrash.CrashBaseRetEvent += OnCrashBaseRetEvent; and handle extra data in the callback.
  
• Judge the type of a callback according to the callback's MSDKBaseRet.MethodNameId. 'string' returned by the interface is the data to be returned by the callback.
  

MSDK_CRASH_CALLBACK_EXTRA_MESSAGE corresponds to extra logs

MSDK_CRASH_CALLBACK_EXTRA_DATA corresponds to extra binary data

Binary data also needs to be converted to string.

• UnrealEngine

It is needed to inherit MSDKCrashObserver to implement two methods of the callback:

OnCrashExtraMessageNotify corresponds to extra logs

OnCrashExtraDataNotify corresponds to extra binary data

4) Demo code

MSDKCrash.SetCrashCallback();		
MSDKCrash.CrashBaseRetEvent += OnCrashBaseRetEvent;		
		
public string OnCrashBaseRetEvent(MSDKBaseRet baseRet)		
{		
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_CRASH_CALLBACK_EXTRA_DATA)		
    {		
// This is a non-Unity process. Be careful not to do any unity-related operations on it		
        return "this is extra data.";		
    }		
    else if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_CRASH_CALLBACK_EXTRA_MESSAGE)		
    {		
       // This is a non-Unity process. Be careful not to do any unity-related operations on it		
       return "this is extra message.";		
    }		
    return "";		
}		
		
//It is needed to remove the listener when destroyed		
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 Set the level of automatic reporting (only support Unity)

1) Functional description

The user can independently set the level of log reporting. For example, Bugly Unity will report logs according to LogError and Exception levels by default. If the user does not want to report logs according to the LogError level, the user can set the level through this interface.

2) Interface declaration

public static void SetAutoReportLogLevel(int level)

3) Description of input parameters

4) Demo code

MSDKCrash.SetAutoReportLogLevel(0);

2.6 Set MSDK's exception stack reporting function

1) Function description

Report App's exception stack through MSDK (Bugly), such as: c#, Lua, etc.

2) Interface Declaration

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) Description of input parameters

4) Demo code

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 Dynamically close Crash reporting (currently only supported by the Bugly channel)

1) Function description

1、In some scenarios, apps do not need to report a crash, such as: some apps do not want to report to Bugly crashes triggered during the killing of processes; at this time, they can call this interface to close crash reporting, but other Bugly functions will not be affected; crashes triggered by the restart of the apps will be reported normally.

2、Dynamically close Crash reporting. Crash reporting can be closed by calling this interface, but other Bugly functions will not be affected; crashes triggered by the restart of the app will be reported normally.

2) Interface Declaration

public static void CloseCrashReport()

static void CloseCrashReport()

3) Demo code

MSDKCrash.CloseCrashReport();

MSDKCrash::CloseCrashReport();