Extending the Package

Overview

The Sparrow Bug Tracking package is a powerful tool for managing and reporting bugs directly from your Unity Editor and your Games from an Ingame-Overlay. It provides an abstract class APISettings that can be extended to connect with different bug tracking APIs.

APISettings

The APISettings class is the core of the Sparrow Bug Tracking package. It provides the following properties:

caption: A virtual string property that can be overridden to provide a custom caption for the API setting.
capabilities: A virtual property that declares what the endpoint can do (for example Capability.Ticketing and/or Capability.ImageUpload), so the system knows whether it can share ticket links or image links with other endpoints.
isWorking: A boolean property that indicates whether the API is working correctly. This is determined by sending a test report to the API.
isActive: A boolean property that indicates whether the API is currently active.

The APISettings class also provides the following methods:

SendReport(ReportData report, Dictionary<string, string> ticketURLs, Dictionary<string, string> imageURLs): An abstract method that must be implemented in a derived class. It should send a report to the bug tracking API and return a Task<bool> indicating whether the report was sent successfully. The two dictionaries let the endpoint publish created ticket links and uploaded image links so other active endpoints can reference them.
MigrateToVersion2(): An abstract method that upgrades the endpoint’s stored secrets to the current encryption version.
CheckEncryptionVersion(): An abstract method that returns the list of EncryptedString secrets the endpoint stores, used to inspect and regenerate encryption keys.
SendTestReport(): A method that sends a test report to the API to check if it’s working correctly.

Unity Editor Interface

In the Unity Editor, each API setting is drawn as a foldout in the DebugSystem inspector that displays the caption and the status of the API (working or not working). When the foldout is expanded, it shows a toolbar for activating or deactivating the API, a label indicating the status of the API, the endpoint-specific settings, and a button for sending a test report.

Extending APISettings

To use the Sparrow Bug Tracking package with a specific bug tracking API, you need to create a class that extends APISettings and implements the abstract members SendReport(...), MigrateToVersion2() and CheckEncryptionVersion(). For more detailed information see the example class below:

using System.Collections.Generic;
using System.Threading.Tasks;
using Sparrow.BugTracking;
using UnityEngine;

[System.Serializable]
public class ExampleAPISettings : APISettings
{
    public override string caption => "Example API Setting";
    public override Capability capabilities => Capability.Ticketing;

    // Store secrets in EncryptedString fields so they are encrypted on disk
    [SerializeField] EncryptedString m_ApiKeySafe = new EncryptedString();
    public string apiKey
    {
        get => m_ApiKeySafe.stringValue;
        set => m_ApiKeySafe.stringValue = value;
    }

    public override async Task<bool> SendReport(ReportData report, Dictionary<string, string> ticketURLs = null, Dictionary<string, string> imageURLs = null)
    {
        // Implement the logic to send a report to the Example API here.
        // This will depend on the specifics of the Example API.
        Debug.Log($"Sending report to Example API: {report.fullLog}");
        return await Task.FromResult(true);
    }

    public override void MigrateToVersion2()
    {
        MigrateEncryptedString(m_ApiKeySafe);
    }

    public override List<EncryptedString> CheckEncryptionVersion()
    {
        return new List<EncryptedString> { m_ApiKeySafe };
    }
}

The inspector UI for an endpoint lives in a separate editor class with a static DrawSpecificEditor method. Create one for your endpoint and register it in APISettingEditors.DrawSpecificEditor so it is drawn together with the built-in endpoints:

using Sparrow.BugTracking;
using UnityEditor;

public class APIEditorExample
{
    public static void DrawSpecificEditor(ExampleAPISettings example)
    {
        example.apiKey = EditorGUILayout.PasswordField("API Key", example.apiKey);
    }
}

// In APISettingEditors.DrawSpecificEditor, add:
// if (setting is ExampleAPISettings) APIEditorExample.DrawSpecificEditor(setting as ExampleAPISettings);

Note

Please remember that this package is intended for use in the Unity Editor and your specific application. Always test your bug reporting functionality thoroughly before releasing your application.

Using the Backend

What to track?

The DebugSystem class in the DebugSystem.cs file allows you to specify what information to include in the bug reports. This is done by setting the boolean values of the following serialized fields:

m_BuildNumber: Includes the current build version from your build settings in your reports.
m_BundleId: Includes the bundle id from your build settings in your reports.
m_OpenSceneCount: Includes the number of open scenes in your reports.
m_OpenSceneList: Includes a list of open scenes in your reports.
m_StartTime: Includes the time when the game is started.
m_CurrentTime: Includes the current time when the log is sent.
m_Platform: Includes the platform the game is run on (Android/iOS etc).
m_DeviceModel: Includes the device model information.
m_DeviceName: Includes the device name information.
m_DeviceType: Includes the device type information.
m_GraphicsDeviceName: Includes the graphics device name information.
m_GraphicsDeviceMemorySize: Includes the graphics device memory size information.
m_IncludeMetrics: Includes current performance metrics (FPS, memory usage, session length) in your reports.
m_CPUInfo, m_RAMInfo, m_StorageInfo, m_OSInfo: Include CPU, RAM, storage and operating system information respectively.
m_IncludeDebugLog: Includes all information that was logged using Debug.Log().
m_IncludeDebugException: Includes all information that was logged using Debug.LogException().
m_IncludeDebugError: Includes all information that was logged using Debug.LogError().
m_IncludeDebugWarnings: Includes all information that was logged using Debug.LogWarning().
m_IncludeDebugAssertion: Includes all information that was logged using Debug.LogAssertion().
m_IncludeStackTraces: Includes stack traces for Exceptions and Errors (when available).
m_IncludeCustomText: You can set a custom text to be included, for example to identify different builds and versions.

When to send it?

The DebugSystem class also allows you to specify when to automatically send bug reports. This is done by setting the boolean values of the following fields:

m_AutoSendOnError: Automatically send a report when an error occurs.
m_AutoSendOnException: Automatically send a report when an exception occurs.
m_AutoSendOnWarning: Automatically send a report when a warning occurs.
m_OnlySendInBuilds: Only send reports in builds and not in the editor.
m_EnableOfflineQueue: Store reports that could not be delivered to any endpoint and retry sending them on the next launch.

Where to send it?

The DebugSystem class allows you to specify where to send the bug reports. This is done by setting the instances of the following properties:

trello: Trello API settings.
github: GitHub API settings.
openproject: OpenProject API settings.
notion: Notion API settings.
email: Email API settings.
discord: Discord API settings.
slack: Slack API settings.
clickup: ClickUp API settings.
imgur: Imgur API settings.
unityCloud: Unity Cloud Diagnostics API settings.
ownEndpoint: Own API Endpoint settings.
jira: Jira API settings.
msTeams: Microsoft Teams API settings.
telegram: Telegram API settings.
gitlab: GitLab API settings.

Each of these properties is an instance of a class that inherits from the APISettings class. You can configure each instance according to the specific API’s requirements.