Bug Reporting SDK Integration Guide for Game Developers

This bug reporting SDK integration guide covers everything you need to know. Integrating a bug reporting SDK should be one of the first things you do when setting up a new game project, and one of the last things you remove before certifying a gold master. The SDK acts as the bridge between your players’ experiences and your team’s ability to understand and fix problems. This guide walks through the integration patterns that work across Unity, Godot, and Unreal Engine—from initial setup through advanced customization.

Phase 1: Basic Integration

The first integration step is always the same regardless of engine: install the SDK, initialize it early, and verify that a test report reaches your dashboard. This should take under 15 minutes.

Unity

using UnityEngine;
using Bugnet;

// Attach to a GameObject in your first scene
// Set Script Execution Order to -100 for early init
public class BugReportInit : MonoBehaviour
{
    [SerializeField] string projectKey = "your-key";

    void Awake()
    {
        BugnetSDK.Init(projectKey);
        DontDestroyOnLoad(gameObject);
    }
}

Godot

# autoload: addons/bugnet/bugnet_manager.gd
extends Node

func _ready() -> void:
    Bugnet.init("your-key")

Unreal Engine

// In your GameInstance Init()
void UMyGameInstance::Init()
{
    Super::Init();
    FBugnetConfig Config;
    Config.ProjectKey = TEXT("your-key");
    UBugnetSDK::Initialize(Config);
}

After initializing, trigger a test report (press the report key, or call the report function directly) and verify it appears in your dashboard with a screenshot, device info, and logs. If this works, your basic integration is complete.

Phase 2: Adding Context

A bug report with just a screenshot and device info is useful. A bug report with game-specific context is powerful. The second integration phase is about wiring your game’s state into the reporting system so every report includes what the player was doing, where they were, and what the game believed was happening.

Scene and level tracking: update the SDK context whenever the player transitions between scenes, levels, or major game areas.

// Unity: track scene changes
void OnEnable()
{
    SceneManager.sceneLoaded += OnSceneLoaded;
}

void OnSceneLoaded(Scene scene, LoadSceneMode mode)
{
    BugnetSDK.SetContext("scene", scene.name);
    BugnetSDK.SetContext("scene_index",
        scene.buildIndex.ToString());
}

# Godot: track scene changes
func _on_scene_changed(scene_path: String) -> void:
    Bugnet.set_context("scene",
        scene_path.get_file().get_basename())

Player identification: attach the player’s ID, display name, or account identifier. This lets you correlate multiple reports from the same player and follow up when the bug is fixed.

Game version and build info: always include the exact build version. When you receive a report, you need to know which version of the code was running. This seems obvious, but many studios forget to update the version string and end up unable to correlate reports with specific builds.

Custom game state: think about what information would help you debug a bug report if you received one right now. Current quest? Active inventory items? Save slot? Last checkpoint? Difficulty setting? Add these as context fields. The cost is one function call per state change; the value is enormous.

Phase 3: Network Considerations

Bug reports include screenshots, logs, and context data. A typical report payload is 200KB–2MB depending on screenshot resolution and log length. Your SDK integration needs to handle network reliability gracefully.

Background upload: never block the game thread while uploading a report. The SDK should queue the report and transmit it on a background thread or via an async HTTP request. The player should see an instant confirmation regardless of network speed.

Retry on failure: if the upload fails (no internet, server error, timeout), the SDK should cache the report locally and retry on the next opportunity. A well-designed SDK handles this automatically, but if you are building custom, implement exponential backoff with a maximum of 3–5 retries.

Bandwidth awareness: on mobile and in bandwidth-constrained environments, compress the screenshot aggressively (JPEG quality 70–80 is usually sufficient) and limit the log payload to the last 50–100 lines. A 200KB report is unnoticeable; a 5MB report on a metered mobile connection is not.

# Godot: bandwidth-conscious screenshot capture
func capture_compressed_screenshot() -> PackedByteArray:
    var image := get_viewport().get_texture().get_image()
    # Resize large screenshots for bandwidth
    if image.get_width() > 1920:
        image.resize(1920, 1080, Image.INTERPOLATE_BILINEAR)
    return image.save_jpg_to_buffer(0.75)

Phase 4: Platform-Specific Considerations

PC (Steam): the most straightforward platform. Full filesystem access for caching reports, reliable internet connectivity, and no platform restrictions on screenshot capture. Map the bug report to both a keyboard key and a controller button for Steam Deck support.

Mobile (iOS/Android): request any necessary permissions (storage for caching, network state for retry logic). Be aggressive about compression. Consider using the system share sheet as an alternative submission path if the network upload fails. Test with airplane mode to verify offline caching works.

Console: each platform has specific requirements for network communication, user data handling, and screenshot capture. The SDK may need platform-specific implementations for these features. Consult the platform TRCs/XRs early in development.

Web (HTML5/WebGL): screenshots must be captured from the WebGL canvas, which has CORS and timing restrictions. Cache reports in IndexedDB if network upload fails. Be mindful of browser memory limits—keep the report payload compact.

Phase 5: Testing the Integration

Before shipping, verify the integration works correctly in these scenarios:

Normal report: player opens form, types description, submits. Report appears in dashboard with screenshot, device info, context, and logs.

Crash report: force a crash and verify it is captured and sent (either immediately or on next launch).

Offline report: disconnect from the internet, submit a report, reconnect, and verify the cached report is sent.

Shipping build: test with the exact build configuration you will ship. Debug and development builds may have different logging levels, assertion behavior, and optimization settings that affect what data the SDK captures.

“We integrated the SDK in development and tested it for months. Then we shipped a Release build and realized we had forgotten to include the SDK’s native crash handler in our linker settings. Three weeks of player crashes went unreported. Always test the shipping build.”

API Design Patterns

Whether you are using Bugnet or building custom, the SDK API surface should follow these patterns:

Init once, early. A single initialization call with the project key, called as early as possible. No re-initialization needed.

SetContext for state. A key-value API for attaching game state. Call it whenever state changes. The SDK accumulates context and attaches the latest values to each report.

ShowReportDialog for player-initiated reports. A single call that handles the UI, screenshot, data collection, and submission. The developer should not need to orchestrate these steps manually.

CaptureException for programmatic reports. An API for sending reports from code without player interaction. Useful for caught exceptions, detected anomalies, or automated test failures.

Related Issues

For a quick-start tutorial that gets you to first report in under 10 minutes, see Add Crash Reporting to Unity or Godot in 10 Minutes. For Unity-specific setup, read Getting Started with Unity. For Godot-specific setup, check out Getting Started with Godot.

The SDK integration is not a one-time task. As your game grows, keep adding context. The more your reports know about your game, the less time you spend asking "what were they doing when this happened?"