Game Engine Integration

Integrate BetaHub directly into your game for seamless in-game bug reporting with automatic media capture.

Overview

BetaHub provides native plugins for popular game engines that enable:

• In-game bug report forms triggered by events or user input
• Automatic video recording of recent gameplay
• Screenshot capture with annotation tools
• Log file attachment for technical debugging
• Optional diagnostic components for geolocation and network latency data
• Customizable reporting workflows

Unity Plugin

Installing BetaHub Unity Plugin

Learn how to install the BetaHub Unity Plugin in your Unity project to enable bug reporting and feedback collection.

Watch Screencast

Quick Setup

1. Install Plugin
   • Open Package Manager in Unity
   • Click + → Add package from git URL
   • Enter: https://github.com/betahub-io/unity-plugin.git
2. Add to Scene
   • Drag BugReportingFormCanvas prefab to your scene
   • Enter your Project ID in the inspector
   • Press F12 in game to test

Installation Details

Prerequisites

• Unity 2021.1 or later
• Project ID from BetaHub (found in project settings)

Step-by-Step Installation

1. Import Package

   Window → Package Manager → + → Add package from git URL
   https://github.com/betahub-io/unity-plugin.git
   

2. Import Samples (Recommended)
   • Expand Samples in Package Manager
   • Click Import to see how the plugin works
3. Install FFmpeg
   • Go to Tools → BetaHub → Install FFmpeg
   • Enables video recording functionality
   • Supports Windows, macOS, and Linux

Configuration Options

BugReportingFormCanvas Settings:

• Shortcut Key (Default: F12) - Key to open bug report form
• Performance Sampler
  • Sample Frequency - How often to sample performance
  • Sample Duration - How long to sample
• Game Recorder
  • Frame Rate (Default: 30) - Video recording frame rate
  • Recording Duration (Default: 60) - Maximum video length

Programmatic Usage

Opening the Bug Report Form

// Get the bug report UI component
BH_BugReportUI bugReportUI = FindObjectOfType<BH_BugReportUI>();

// Open the form
bugReportUI.SetActive(true);

Default Inclusions

Adding Screenshots

// Add a screenshot to the bug report
bugReportUI.AddScreenshot(screenshotPath, removeAfterUpload: true);

Parameters:

• path - Full path to screenshot file
• removeAfterUpload - Delete file after successful upload

Adding Custom Log Files

// Add custom log files
bugReportUI.AddLog(logFilePath, removeAfterUpload: true);

Parameters:

• path - Full path to log file
• removeAfterUpload - Delete file after successful upload

Optional Diagnostic Components

The Unity plugin includes optional components that enhance bug reports with additional diagnostic information. These components are not attached to the prefabs by default and must be manually added to provide enhanced debugging capabilities.

GeolocationProvider

Automatically collects the user’s country and ISP information based on their IP address to help identify location-specific issues and provide geographic context for bug reports.

How It Works:

• Detects the user’s country and ISP via IP geolocation using BetaHub’s ping endpoint
• Automatically includes country and ISP data in bug reports as custom fields
• ISP data is resolved to readable company names on the BetaHub dashboard

Setup Instructions:

1. Select the GameObject containing your BugReportUI component
2. Click Add Component and search for GeolocationProvider
3. Configure the provider in the inspector:
   • Enable Geolocation - Toggle to enable/disable country code collection
   • Enable ASN Collection - Toggle to enable/disable ISP/ASN data collection
   • Geolocation Endpoint - API endpoint for geolocation (default: https://ping.betahub.io/ping.txt)
   • Timeout Seconds - Request timeout (default: 5 seconds)
4. The component will automatically link itself to the BugReportUI on the same GameObject

Required Custom Fields: Before using GeolocationProvider, ensure these custom fields exist in your BetaHub project:

• country (text) - Reporter’s country code for geographic bug distribution analysis
• asn (text) - ISP/company name from reporter’s IP address for network provider insights

LatencyProvider

Measures network latency to help diagnose network-related issues and provide connection quality context for bug reports.

How It Works:

• Supports two measurement methods: ICMP ping (default) or HTTP-based latency measurement
• Automatic fallback from ICMP to HTTP if ICMP fails consistently
• Two collection modes:
  • OnBugReport - Collects pings only when bug report window opens (default)
  • Continuous - Continuously collects pings in the background at regular intervals
• Supports multiple target hosts for comprehensive network analysis
• Calculates minimum, maximum, and average latency plus packet loss statistics

Setup Instructions:

1. Select the GameObject containing your BugReportUI component
2. Click Add Component and search for LatencyProvider
3. Configure the provider in the inspector:
   • Enable Latency - Toggle to enable/disable latency measurement
   • Collection Mode - Choose between OnBugReport (default) or Continuous collection
   • Ping Method - Select ICMP (default) or HTTP ping method
   • ICMP Target Hosts - List of hosts for ICMP ping (default: ping.betahub.io)
   • HTTP Endpoint - API endpoint for HTTP latency testing (default: https://ping.betahub.io/ping.txt)
   • Min Ping Requests - Minimum number of ping requests per host (default: 10, range: 1-20)
   • Timeout Seconds - Request timeout per ping (default: 5 seconds)
   • Delay Between Requests - Delay between consecutive pings (default: 0.1 seconds)
   • Ping Interval - Interval between background pings in continuous mode (default: 15 seconds)
4. The component will automatically link itself to the BugReportUI on the same GameObject

Required Custom Fields: Before using LatencyProvider, ensure this custom field exists in your BetaHub project:

• latency (text) - Network latency measurements for connection quality analysis

Custom Field Validation

The plugin automatically validates that required custom fields exist in your BetaHub project when providers are attached. If any required fields are missing or misconfigured, you’ll see error messages with direct links to configure them.

Validation Requirements:

• Custom fields must exist in your BetaHub project
• Fields must be marked as tester_settable to allow the plugin to set their values
• Field types must match the expected type (text for all current providers)

Data Integration

When both components are enabled, bug reports will include custom fields like:

Custom Fields:
country=US
asn=Cloudflare, Inc.
latency=ping.betahub.io: min/avg/max = 45ms/67ms/89ms (10/10 requests)

This data appears in the BetaHub dashboard and can be used for:

• Geographic Analysis - Identifying region-specific issues and user distribution
• ISP Analysis - Understanding which internet service providers may be experiencing issues
• Network Diagnosis - Correlating bugs with connection quality and packet loss rates
• Performance Optimization - Understanding user network conditions across different providers
• Support Prioritization - Triaging issues based on user location, ISP, and connectivity quality

Troubleshooting

Common Issues:

• “No latency data available” - All ping requests failed. Check network connectivity and endpoint accessibility
• “No country information found” - Geolocation service didn’t return expected data. May indicate network issues or endpoint changes
• Warning messages in console - If components are not on the same GameObject as BugReportUI, you’ll see warnings with setup instructions
• Custom field validation errors - Missing or misconfigured custom fields in your BetaHub project. Follow the provided links to configure them

Advanced Integration

Event-Driven Reporting

public class CrashHandler : MonoBehaviour
{
    void OnApplicationException(string condition, string stackTrace, LogType type)
    {
        if (type == LogType.Exception || type == LogType.Error)
        {
            // Take screenshot of error state
            StartCoroutine(CaptureAndReport());
        }
    }
    
    IEnumerator CaptureAndReport()
    {
        // Capture screenshot
        yield return new WaitForEndOfFrame();
        ScreenCapture.CaptureScreenshot("crash_screenshot.png");
        
        // Open bug report with screenshot
        BH_BugReportUI bugReportUI = FindObjectOfType<BH_BugReportUI>();
        bugReportUI.AddScreenshot("crash_screenshot.png", true);
        bugReportUI.SetActive(true);
    }
}

Custom Button Integration

public class UIManager : MonoBehaviour
{
    public Button reportBugButton;
    
    void Start()
    {
        reportBugButton.onClick.AddListener(OpenBugReport);
    }
    
    void OpenBugReport()
    {
        BH_BugReportUI bugReportUI = FindObjectOfType<BH_BugReportUI>();
        bugReportUI.SetActive(true);
    }
}

Unreal Plugin

Installing BetaHub Unreal Plugin

Learn how to install the BetaHub Unreal Plugin in your Unreal project to enable bug reporting and feedback collection.

Watch Screencast

Quick Setup

1. Install Plugin
   • Create Plugins folder in project root
   • Download latest release from GitHub
   • Extract to YourProject/Plugins/BetaHubBugReporter/
   • Restart Unreal Editor
2. Configure
   • Open Project Settings → BetaHub Bug Reporter
   • Enter your Project ID
   • Press F12 in game to test

Installation Details

Prerequisites

• Unreal Engine (compatible versions listed on GitHub)
• Project ID from BetaHub

Step-by-Step Installation

1. Prepare Directory

   YourProject/
   ├── Plugins/           (create if doesn't exist)
   │   └── BetaHubBugReporter/
   

2. Download and Extract
   • Visit GitHub Releases
   • Download latest .zip file
   • Extract contents to Plugins/BetaHubBugReporter/
3. Rebuild Plugin
   • Restart Unreal Editor
   • Click ‘Yes’ when prompted to rebuild
   • Wait for compilation to complete
4. Verify Installation
   • Go to Edit → Plugins
   • Search for “BetaHub Bug Reporter”
   • Ensure plugin is enabled

Configuration Settings

Project Settings → BetaHub Bug Reporter:

• API Endpoint - BetaHub API URL (default: https://app.betahub.io)
• Project ID - Your project identifier
• Spawn Background Service on Startup - Auto-start service
• Enable Shortcut - Enable F12 hotkey
• Shortcut Key - Customizable trigger key
• Max Recorded Frames - Video recording limit
• Max Recording Duration - Maximum video length
• Report Form Widget Class - Custom UI widget (default: BugReportForm)
• Popup Widget Class - Custom popup widget (default: BugReportFormPopup)

Programmatic Usage

Blueprint Integration

Available Blueprint Nodes:

• Start Service - Begin background recording
• Stop Service - End background recording
• Spawn Bug Report Widget - Open bug report form

C++ Integration

#include "BH_Manager.h"

// Create manager instance
UBH_Manager* BugReportManager = NewObject<UBH_Manager>();

// Control background service
BugReportManager->StartService();
BugReportManager->StopService();

// Open bug report form
BugReportManager->SpawnBugReportWidget(true); // bTryCaptureMouse

Advanced Integration

Custom Event Triggers

// Trigger bug report on game crash
void AMyGameMode::HandleCrash()
{
    // Capture current state
    UBH_Manager* BugReportManager = GetBugReportManager();
    BugReportManager->SpawnBugReportWidget(true);
}

Performance Monitoring Integration

// Monitor FPS and trigger reports on performance issues
void APerformanceMonitor::CheckPerformance()
{
    float CurrentFPS = 1.0f / GetWorld()->GetDeltaSeconds();
    
    if (CurrentFPS < MinAcceptableFPS)
    {
        // Auto-trigger performance bug report
        UBH_Manager* BugReportManager = GetBugReportManager();
        BugReportManager->SpawnBugReportWidget(false);
    }
}

Best Practices

Integration Strategy

Start Simple:

• Begin with default F12 hotkey
• Test with basic bug reports
• Gradually add custom triggers

User Experience:

• Provide clear instructions to players
• Make bug reporting optional
• Avoid interrupting critical gameplay

Media Capture:

• Take screenshots before opening menus
• Keep video recordings focused and relevant
• Include relevant log files

Performance Considerations

Video Recording:

• Monitor impact on game performance
• Adjust frame rate based on target platform
• Consider memory usage for longer recordings

Background Services:

• Start services only when needed
• Stop services during intensive gameplay
• Monitor CPU and memory overhead

Testing and Validation

Development Testing:

• Test in various game states
• Verify media capture quality
• Ensure log files contain relevant information

User Acceptance Testing:

• Train testers on bug reporting process
• Gather feedback on form usability
• Iterate based on user experience

Troubleshooting

Common Issues

Unity Plugin:

• FFmpeg Not Found - Run Tools → BetaHub → Install FFmpeg
• Form Not Opening - Check Project ID configuration
• Videos Not Recording - Verify FFmpeg installation and permissions

Unreal Plugin:

• Plugin Not Loading - Verify extraction path and restart editor
• Missing Permissions - Check file permissions in Plugins folder
• Blueprint Errors - Ensure plugin is enabled in Project Settings

Getting Help

For technical support:

• Check plugin GitHub repositories for issues and updates
• Join our Discord server for community help
• Review the FAQ for common solutions

Next Steps

• External Tool Integrations - Connect with project management tools
• API Access - Custom integration development
• Advanced Features - Explore AI-powered capabilities