Dependencies

• Working familiarity with incident reports - If you're not familiar with the default incident reports the Metaplay SDK offers, you can find out more about them in the View Player Incident Reports section of the Introduction to the LiveOps Dashboard page.

Overview

The Metaplay SDK provides a powerful built-in incident report system that should cover most cases where you would want to record problems on the client, including networking issues, unhandled exceptions, and more. Furthermore, the SDK also supports creating and using custom incident report types.

Creating Custom Incident Report Types

To implement a custom incident report type, start by creating a class in shared code that derives from PlayerIncidentReport. The combination of Type, SubType and GetReason are used to calculate the "fingerprint" of the incident, which is used to group the incidents in the LiveOps Dashboard's Unique Incidents view. The Type field is also used for manual filtering on the LiveOps Dashboard.

[MetaSerializableDerived(101)]
public class HandledErrorPlayerIncident : PlayerIncidentReport
{
    [MetaMember(1)] public string ExceptionType;
    [MetaMember(2)] public string ExceptionMessage;
    [MetaMember(3)] public string StackTrace;

    public HandledErrorPlayerIncident() { }
    public HandledErrorPlayerIncident(
        SharedIncidentInfo info, 
        string exceptionType, 
        string exceptionMessage, 
        string stackTrace) 
        : base(info)
    {
        ExceptionType    = exceptionType;
        ExceptionMessage = exceptionMessage;
        StackTrace       = stackTrace;
    }

    // Type of incident, usually name of the C# type.
    public override string Type => nameof(HandledErrorPlayerIncident);
    // Subtype of the incident, for example the name of the error that prompted the incident. Shown together with the Type in the dashboard incident details page.
    public override string SubType => ExceptionType;
    // Reason for the incident, for example the message of the error that prompted the incident. Shown as a preview of the incident on the dashboard incident list view.
    // Used together with Type and Subtype to calculate the "fingerprint" of the incident to use for grouping incidents on the dashboard unique incidents view. 
    public override string GetReason()
    {
        return ExceptionMessage;
    }
}

INFO

Currently, the dashboard looks for certain keywords for visualizing fields in a special way. These include "ExceptionMessage" and "StackTrace". If you include exception messages or stack traces as part of your custom incident, match the aforementioned typing and they'll be correctly visualized on the dashboard!

By default, 100% of incidents of a given type are uploaded to the server. You can reduce the upload percentage of certain types of incidents by overriding it in the runtime options:

## Change HandledErrorPlayerIncident type's upload percentage to 50% 
PlayerIncident:
  UploadPercentagesPerIncidentType:
    "HandledErrorPlayerIncident": 50

Reporting Incidents

To report an incident and add an associated analytics event, use MetaplaySDK.IncidentTracker.AddIncidentAndAnalyticsEvent(), or MetaplaySDK.IncidentTracker.AddIncidentWithNetworkReportAndAnalyticsEvent() if you want to include a network diagnostic report. Note that the IncidentTracker can throttle incident reports if they happen too frequently (more than 5 per minute by default). You can bypass the throttling by setting the parameter useThrottle to false. Alternatively, you can directly add an incident report to the IncidentRepository using MetaplaySDK.IncidentRepository.AddOrUpdate(). This will add the incident report without the associated analytics event.

Use IncidentTracker.GetSharedIncidentInfo() to populate the report with commonly needed info about the application, system and client logs.

public static void ReportHandledErrorPlayerIncident(Exception ex)
{
    MetaplaySDK.IncidentTracker.AddIncidentAndAnalyticsEvent(
        new HandledErrorPlayerIncident(
            MetaplaySDK.IncidentTracker.GetSharedIncidentInfo(),
            ex.GetType().ToString(),
            ex.Message,
            ex.StackTrace
            ));
}

If you need to create a player incident from the server, you can directly persist it to the database as follows:

// Persist an incident directly on the server and inform the PlayerActor
await PlayerIncidentStorage.SerializeAndPersistIncidentAsync(playerId, incidentReport, informPlayerActor: true, sourceEntity: this);