Setting Up Automatic Bug Capture in Unity with Bugnet

This getting started Unity guide walks you through the setup process step by step. Your players are encountering bugs you will never hear about. Fewer than 5% of players who hit a crash will file a report, which means the vast majority of issues slip through unnoticed. The Bugnet Unity SDK changes that by capturing crashes, exceptions, screenshots, and player context automatically—so you can fix the bugs that are quietly driving players away.

This guide walks you through the full setup: installing the SDK, configuring automatic capture, choosing how players trigger manual reports, and submitting bug reports programmatically from your own code. By the end, you will have a Unity project that catches every crash and delivers rich, actionable reports straight to your Bugnet dashboard.

Step 1: Install the Bugnet Package

You have two options for adding Bugnet to your Unity project. The recommended approach is using the Unity Package Manager (UPM), which makes it easy to update the SDK later. Alternatively, you can import a .unitypackage file directly.

Option A: Unity Package Manager (recommended)

Open your project in Unity, then navigate to Window → Package Manager. Click the + button in the top-left corner and select Add package from git URL. Paste the following URL:

https://github.com/ArcticLabs/bugnet-unity-sdk.git

Unity will download and install the package automatically. You can verify the installation by checking for the Bugnet namespace in your scripts.

Option B: Manual .unitypackage import

Download the latest BugnetSDK.unitypackage from the Bugnet SDKs page. In Unity, go to Assets → Import Package → Custom Package, select the downloaded file, and click Import. This will add the Bugnet SDK folder under Assets/Bugnet/.

Step 2: Attach BugnetSDK to a Persistent GameObject

The Bugnet SDK needs to survive scene transitions so it can capture crashes and exceptions throughout the entire play session. The simplest approach is to attach it to a GameObject in your first scene and mark it with DontDestroyOnLoad.

Create an empty GameObject in your startup scene and name it BugnetManager. Add a new script called BugnetInit.cs with the following code:

using UnityEngine;
using Bugnet;

public class BugnetInit : MonoBehaviour
{
    void Awake()
    {
        DontDestroyOnLoad(this.gameObject);

        BugnetSDK.Init("YOUR_API_KEY", new Config
        {
            GameId   = "YOUR_GAME_ID",
            AutoLogs = true,
            Trigger  = Trigger.Shake,
        });

        Debug.Log("Bugnet SDK initialized");
    }
}

Replace YOUR_API_KEY and YOUR_GAME_ID with the values from your Bugnet dashboard under Project Settings → SDK Keys. The AutoLogs flag tells the SDK to automatically capture Unity's Application.logMessageReceived events, including unhandled exceptions and crash stack traces.

Keep your API key out of version control. We recommend loading it from a ScriptableObject or environment config that is excluded from your repository.

Step 3: Configure Trigger Modes

The Trigger setting controls how players open the manual bug report form during gameplay. Bugnet supports several trigger modes that you can mix and match depending on your platform and audience.

• Trigger.Shake — Players shake their mobile device to open the report form. Ideal for iOS and Android builds.
• Trigger.UI — Displays a small floating button on screen that players can tap or click. Works well across all platforms.
• Trigger.Keyboard — Binds a keyboard shortcut (default: F12) to open the report form. Best for desktop builds and during internal playtesting.
• Trigger.None — Disables the built-in trigger entirely. Use this when you want to invoke reports only from your own UI or code.

You can combine multiple triggers by using a bitwise OR:

BugnetSDK.Init("YOUR_API_KEY", new Config
{
    GameId   = "YOUR_GAME_ID",
    AutoLogs = true,
    Trigger  = Trigger.UI | Trigger.Keyboard,
});

This configuration shows the floating report button and also listens for the F12 key, giving players two ways to submit feedback. During development, we recommend enabling Trigger.Keyboard at a minimum so your QA team can file reports without leaving the game.

Step 4: Automatic Crash Logs and Screenshots

With AutoLogs set to true, the SDK automatically captures three categories of data whenever something goes wrong:

• Crash logs and stack traces: Every unhandled exception, native crash, and LogError call is recorded with a full stack trace, timestamp, and the scene that was active at the time.
• Screenshot attachment: When a player submits a report (or when a crash is detected), the SDK captures a screenshot of the current frame. This gives you immediate visual context without requiring the player to describe what they saw.
• Player context metadata: Each report includes device model, OS version, GPU, RAM, current scene name, play session duration, and any custom key-value pairs you attach. This metadata is what transforms a vague "it crashed" into a reproducible issue.

You can enrich the automatic context with your own gameplay data using SetContext. For example, attaching the player's current level and character class helps you spot patterns when triaging reports:

BugnetSDK.SetContext("player_level", PlayerStats.Level.ToString());
BugnetSDK.SetContext("character_class", PlayerStats.ClassName);
BugnetSDK.SetContext("save_slot", SaveManager.ActiveSlot.ToString());

Call SetContext whenever these values change—such as after a level up or scene transition—and the SDK will include the latest values in every subsequent report.

Step 5: Submitting Bug Reports from Code

Sometimes you want to file a bug report programmatically, without any player interaction. This is useful for catching soft errors that do not trigger a crash but still indicate something is wrong—a failed network request, a missing asset, or a gameplay state that should never occur.

Use BugnetSDK.Report to submit a report directly:

public void OnInventoryLoadFailed(string error)
{
    BugnetSDK.Report(new BugReport
    {
        Title       = "Inventory failed to load",
        Description = $"Could not load inventory: {error}",
        Severity    = Severity.High,
        Tags        = new[] { "inventory", "data-load" },
        Screenshot  = true,
    });

    // Show fallback UI to the player
    ShowInventoryErrorDialog();
}

The Screenshot flag tells the SDK to capture the current frame along with the report. You can also set it to false if you are filing a background report where a screenshot would not be meaningful.

Programmatic reports appear in your Bugnet dashboard alongside player-submitted and auto-captured reports. They are tagged with a source:code label so you can filter and prioritize them separately.

What You Get in the Dashboard

Once the SDK is running in your build, every crash and report flows into the Bugnet dashboard in real time. Here is what you can expect:

• Auto-grouped issues: Bugnet clusters reports with the same root cause, so 500 identical null reference crashes show up as a single issue with an affected-player count rather than 500 separate tickets.
• Player impact scoring: Each issue is ranked by how many unique players it affects and where those players are in the game. A tutorial crash that blocks new players is automatically prioritized above a cosmetic glitch in endgame content.
• Device and platform breakdown: See at a glance whether a crash is isolated to a specific GPU, OS version, or device family. This helps you decide whether a targeted workaround is sufficient or a full fix is needed.
• Timeline view: Track how crash rates change across builds. After you ship a hotfix, you can verify that the issue is resolved by comparing crash counts before and after the update.

Five minutes of setup. Every crash captured. No player report required.

Quick Checklist

1. Install the Bugnet SDK via UPM or .unitypackage.
2. Attach BugnetInit to a persistent GameObject with DontDestroyOnLoad.
3. Call BugnetSDK.Init with your API key, game ID, and AutoLogs = true.
4. Choose a trigger mode that fits your platform (Shake, UI, Keyboard, or a combination).
5. Use SetContext to attach gameplay metadata like player level and scene name.
6. Use BugnetSDK.Report to catch soft errors that do not trigger crashes.
7. Open your Bugnet dashboard and verify that reports are arriving.

That is everything you need to go from zero visibility into player crashes to a fully automatic bug capture pipeline. The entire integration takes about five minutes, and the first crash report will likely teach you something about your game that you did not know.