LogoLogo
HomePlatform IntegrationsDownloadsLogin
  • Welcome
  • 📌Introduction
    • Getting Started
      • Signing Up
      • Creating a Database
      • Platform Integrations
        • 💻Desktop
          • BugSplat Crash Reporting Library for Windows (Native C++)
            • Full Memory Dumps
            • Windows (Native C++) Dependencies
          • Windows (.NET Framework)
          • macOS
          • Linux
        • 🔀Cross-Platform
          • .NET Standard
          • Breakpad (Deprecated)
          • Crashpad
            • How to Build Google Crashpad
          • Deno
          • Electron
          • Java
          • Node.js
          • Python
          • Qt
        • 🎮Game Development
          • CRYENGINE
          • Nintendo Switch
          • PlayStation
          • Unreal Engine
            • Unreal Engine Plugin
          • Unity
          • Xbox
        • 📱Mobile
          • Android
          • Ionic
          • iOS
          • React Native
        • 🕸️Web
          • Angular
          • JavaScript
          • React
          • Vue
        • ⌛Downloads
      • Platform Samples
        • BugSplatTester (iOS)
        • BugSplatTester (macOS)
        • myConsoleCrasher (C++)
          • Address Sanitizer Reports
        • my-android-crasher
        • my-angular-crasher
        • my-electron-crasher
        • my-java-crasher
        • my-node-crasher
        • my-qt-crasher
        • my-react-crasher
        • my-unity-crasher
        • my-unreal-crasher
      • Inviting Team Members
      • Importing Crashes
      • Troubleshooting
      • Quickly Submitting Your First Crash in Under 5 Minutes
    • Development
      • Using the App
      • Symbol Files
        • Common Symbols
        • How to Manually Upload Symbols
        • Source Maps
        • Symbol Servers
        • Working with Symbol Files in Windows Environments
      • Searching
        • Table Filtering
        • Table Grouping
      • Grouping Crashes
      • Commenting
      • Integrations and Third Party Tools
        • Configurable Alerts
          • Slack
          • Microsoft Teams
          • Discord
          • Email
          • Webhook
        • Issue Trackers
          • Azure DevOps
          • Favro
          • Jira
          • GitHub Issues
          • GitLab
          • Monday.com
          • YouTrack
          • Auto-Creating Defects from BugSplat Databases in Attached Third-Party Issue Trackers
      • API
        • Web Application Endpoints
          • Charting
          • Company
          • Crash
          • Crashes
          • Crash Groups
          • Databases
          • Defect
          • Events
          • Import/Migrate
          • Support Response
          • User (GDPR)
          • Users
          • Versions
        • Crash Post Endpoints
        • OAuth2
        • Defect Tracker Options
        • Paging, Filtering, and Grouping
        • Platform Specific API's
          • C++ Native API
          • .NET API
    • Production
      • Versions
      • 🆕Regression Alerts
      • Security and Compliance
        • Security Program
        • BugSplat Security Program Inquirys
        • SOC 2
        • GDPR & UK GDPR Compliance
        • Avoid Collecting Personally Identifiable Information (PII)
        • Crash Expiry
        • Terms
        • Privacy Policy
      • Support Responses
      • BugSplat Status
  • 🍎Education
    • BugSplat Terminology
    • How-Tos
      • Creating Defects
      • Contacting End-Users
      • Crash Dialog Branding
      • Reprocess Crashes
      • Batch Reprocess Crashes
      • Using the Crash Attribute Feature
      • Send Feedback
      • Remove Crashes
    • Videos
      • BugSplat Product Walkthrough
    • FAQs
      • How Do I Upload Crashes with Python?
      • How Do I Remove Symbol Files?
      • Crash details 'Active Thread'
      • How long does it take to process a crash?
      • How BugSplat handles large crash volumes
      • How Does Crash Rate Limiting Work?
      • Add Custom Branding to Support Response
      • Finding Missing Reports
      • Using Dark Mode
      • What If My App or Game Grows Quickly?
      • Does BugSplat have an effect on application performance?
      • Manually Upload Crash Reports to BugSplat
      • How to configure proxy settings in BugSplat
      • Using BugSplat's public database
      • How to Upload Symbol Files with Symbol-Upload
      • Using SendPdbs to Automatically Upload Symbol Files
      • Managing Symbol Space
      • Why Group Crashes?
      • Uploading third-party DLLs without PDB files
      • Localized Support Responses for Windows C++, .NET, and macOS
      • BugSplat application uptime data
        • What are the upload size considerations with BugSplat accounts.
      • Is an application's source code safe when using BugSplat?
      • How to get correct callstacks with BugSplat in Steam
      • What is a crash reporter?
      • Common End-User Questions
        • Missing BugSplat.dll
        • What should I do if I get a BugSplat?
        • What is BsSndRpt.exe?
        • My software just crashed. Should I contact BugSplat for help?
  • 🏢Administration
    • Billing
      • Free Trial Overview
      • Plans and Billing Overview
      • How to Sign Up for a BugSplat Plan
      • Viewing Account Usage
      • Upgrading, Changing, or Canceling Your Plan
        • Upgrading or Downgrading Your Plan
        • Adding Additional Crashes and Storage Space
        • Updating Credit Card and Billing Information and Viewing Billing History
        • Updating Tax and VAT Information
        • Canceling Your Plan
      • Free and Discounted Plans
        • Free Plan Overview
        • Free Crash Reporting for Indie Game Development
        • Education
        • Open-Source
        • Good Causes
      • Plans, Upgrades, and Payments FAQ
        • Fair-Refund Policy
        • Update to Our Legacy Plans Guide
        • Updates to BugSplat Pricing Plans - March 2024
        • Using Coupons and Promotions at BugSplat
        • What is 'High Volume Fractional Crash Processing'?
    • Account
      • Migrating Databases
      • Deleting Databases
      • Deleting a Company Account
      • Changing Company Name
    • User Management
      • User Permissions
      • Deleting a User
      • Requesting Access
      • Login Page and Options
      • Password Settings and Reset Options
        • Required Password Reset - August 4th, 2023
      • Single Sign-On (SSO)
      • Multi-Factor Authentication (MFA)
      • Enforce MFA
      • Adding New Users in Companies with Multiple Databases
    • Contact us
  • 🐛About
    • What is BugSplat?
    • Why BugSplat?
    • Who is BugSplat?
      • Our Values
      • Charitable Giving
      • Brand Guidelines
    • Partnerships
    • Misc
      • Promotions
        • March 2024 - Game Developer Free Months of Service
      • Giveaways
        • April 8 - April 22, 2025
        • Feb 18 - March 17, 2025
        • Jan 15 - Feb 13, 2025
        • December 19-29, 2024
        • November 21–28, 2024
        • October 17-24th, 2024
        • September 19-26th, 2024
        • July 18 - July 23, 2024
        • April 18 - May 12, 2024
        • March 18 - April 03, 2024
        • November 15-30, 2023
        • October 9-23, 2023
  • 🔀Changelog
    • Changelog
Powered by GitBook
On this page
  • 🏗 Installation
  • 🧑‍🏫 Sample
  • ⚙️ Configuration
  • ⌨️ Usage
  • 🪟 Windows
  • 🌎 UWP
  • 🤖 Android
  • 🍎 iOS
  • 🧩 API
  • 🧑‍💻 Contributing

Was this helpful?

  1. Introduction
  2. Getting Started
  3. Platform Integrations
  4. Game Development

Unity

PreviousUnreal Engine PluginNextXbox

Last updated 10 months ago

Was this helpful?

🏗 Installation

BugSplat's com.bugsplat.unity package can be added to your project via or a URL to our git .

OpenUPM

Information on installing OpenUPM can be found . After installing OpenUPM, run the following command to add BugSplat to your project.

openupm add com.bugsplat.unity

Git

Information on adding a Unity package via a git URL can be found .

https://github.com/BugSplat-Git/bugsplat-unity.git

🧑‍🏫 Sample

After installing com.bugsplat.unity, you can import a sample project to help you get started with BugSplat. Click here if you'd like to skip the sample project and get straight to the instructions.

To import the sample, click the carrot next to Samples to reveal the my-unity-crasher sample. Click Import to add the sample to your project

In the Project Assets browser, open the Sample scene from Samples > BugSplat > Version > my-unity-crasher > Scenes.

Next, select Samples > BugSplat > Version > my-unity-crasher to reveal the BugSplatOptions object. Click BugSplatOptions and replace the database value with your BugSplat database.

⚙️ Configuration

BugSplat's Unity integration is flexible and can be used in various ways. The easiest way to get started is to attach the BugSplatManager Monobehaviour to a GameObject.

BugSplatManager needs to be initialized with a BugSplatOptions serialized object. A new instance of BugSplatOptions can be created through the Asset Create menu.

Configure fields as appropriate. Note that if Application or Version are left empty, BugSplat will default these values to Application.productName and Application.version, respectively

Finally, provide a valid BugSplatOptions to BugSplatManager

⌨️ Usage

Adding Metadata

First, find your instance of BugSplat. The following is an example of how to find an instance of BugSplat via BugSplatManager:

var bugsplat = FindObjectOfType<BugSplatManager>().BugSplat;

You can extend BugSplat by setting the following properties:

bugsplat.Attachments.Add(new FileInfo("/path/to/attachment.txt"));
bugsplat.Description = "description!";
bugsplat.Email = "fred@bugsplat.com";
bugsplat.Key = "key!";
bugsplat.Notes = "notes!";
bugsplat.User = "Fred";
bugsplat.CaptureEditorLog = true;
bugsplat.CapturePlayerLog = false;
bugsplat.CaptureScreenshots = true;

You can use the Notes field to capture arbitrary data such as system information:

void Start()
{
    bugsplat = FindObjectOfType<BugSplatManager>().BugSplat;
    bugsplat.Notes = GetSystemInfo();
}

private string GetSystemInfo()
{
    var info = new Dictionary<string, string>();
    info.Add("OS", SystemInfo.operatingSystem);
    info.Add("CPU", SystemInfo.processorType);
    info.Add("MEMORY", $"{SystemInfo.systemMemorySize} MB");
    info.Add("GPU", SystemInfo.graphicsDeviceName);
    info.Add("GPU MEMORY", $"{SystemInfo.graphicsMemorySize} MB");

    var sections = info.Select(section => $"{section.Key}: {section.Value}");
    return string.Join(Environment.NewLine, sections);
}

Try/Catch Reporting

Exceptions can be sent to BugSplat in a try/catch block by calling Post.

try
{
    throw new Exception("BugSplat rocks!");
}
catch (Exception ex)
{
    StartCoroutine(bugsplat.Post(ex));
}

The default values specified on the instance of BugSplat can be overridden in the call to Post. Additionally, you can provide a callback to Post that will be invoked with the result once the upload is complete.

var options = new ReportPostOptions()
{
    Description = "a new description",
    Email = "barney@bugsplat.com",
    Key = "a new key!",
    Notes = "some new notes!",
    User = "Barney"
};

options.AdditionalAttachments.Add(new FileInfo("/path/to/additional.txt"));

static void callback()
{
    Debug.Log($"Exception post callback!");
};

StartCoroutine(bugsplat.Post(ex, options, callback));

Preventing Repeated Reports

By default, BugSplat prevents reports from being sent at a rate greater than 1 per every 60 seconds. You can override the default crash report throttling implementation by setting ShouldPostException on your BugSplat instance. To override ShouldPostException, assign the property a new Func<Exception, bool> value. Be sure your new implementation can handle a null value for Exception!

The following example demonstrates how you could implement your own time-based report throttling mechanism:

var lastPost = new DateTime(0);

bugsplat.ShouldPostException = (ex) =>
{
    var now = DateTime.Now;

    if (now - lastPost < TimeSpan.FromSeconds(3))
    {
        Debug.LogWarning("ShouldPostException returns false. Skipping BugSplat report...");
        return false;
    }

    Debug.Log("ShouldPostException returns true. Posting BugSplat report...");
    lastPost = now;

    return true;
};

Support Response

BugSplat has the ability to display a support response to users who encounter a crash. You can show your users a generalized support response for all crashes, or a custom support response that corresponds to the type of crash that occurred. Defining a support response allows you to alert users that bug has been fixed in a new version, or that they need to update their graphics drivers.

private string infoUrl = "";

public void Event_CatchExceptionThenPostNewBugSplat()
{
    try
    {
        GenerateSampleStackFramesAndThrow();
    }
    catch (Exception ex)
    {
        var options = new ReportPostOptions()
        {
            Description = "a new description"
        };

        StartCoroutine(bugsplat.Post(ex, options, ExceptionCallback));
    }
}

void ExceptionCallback(ExceptionReporterPostResult result)
{
    UnityEngine.Debug.Log($"Exception post callback result: {result.Message}");

    if (result.Response == null) {
        return;
    }

    UnityEngine.Debug.Log($"BugSplat Status: {result.Response.status}");
    UnityEngine.Debug.Log($"BugSplat Crash ID: {result.Response.crashId}");
    UnityEngine.Debug.Log($"BugSplat Support URL: {result.Response.infoUrl}");

    infoUrl = result.Response.infoUrl;
}

private void OpenUrl(string url)
{
    var escaped = url.Replace("?", "\\?").Replace("&", "\\&").Replace(" ", "%20").Replace("!", "\\!");

#if UNITY_STANDALONE_WIN || UNITY_EDITOR_WIN || UNITY_WSA
    Process.Start(url);
#elif UNITY_STANDALONE_OSX || UNITY_EDITOR_OSX
    Process.Start("open", escaped);
#elif UNITY_STANDALONE_LINUX || UNITY_EDITOR_LINUX
    Process.Start("xdg-open", escaped);
#else
    UnityEngine.Debug.Log($"OpenUrl unsupported platform: {Application.platform}");
#endif
}

When an exception occurs, a page similar to the following will open in the user's browser on Windows, macOS, and Linux.

🪟 Windows

Symbols

Minidumps

The methods PostCrash, PostMostRecentCrash, and PostAllCrashes can be used to upload minidumps to BugSplat. We recommend running PostMostRecentCrash when your game launches.

StartCoroutine(bugsplat.PostCrash(new FileInfo("/path/to/crash/folder")));
StartCoroutine(bugsplat.PostMostRecentCrash());
StartCoroutine(bugsplat.PostAllCrashes());

Each of the methods that post crashes to BugSplat also accept a MinidumpPostOptions parameter and a callback. The usage of MinidumpPostOptions and callback are nearly identical to the ExceptionPostOptions example listed above.

You can generate a test crash on Windows with any of the following methods.

Utils.ForceCrash(ForcedCrashCategory.Abort);
Utils.ForceCrash(ForcedCrashCategory.AccessViolation);
Utils.ForceCrash(ForcedCrashCategory.FatalError);
Utils.ForceCrash(ForcedCrashCategory.PureVirtualFunction);

🌎 UWP

To use BugSplat in a Universal Windows Platform application, you will need to add some capabilities to the Package.appxmanifest file in the solution directory that Unity generates at build time.

Capabilities

Reporting exceptions, crashes, and uploading log files requires the Internet (Client) capability.

Minidumps

To upload minidumps from %LOCALAPPDATA%\CrashDumps you will also need to add the broadFileSystemAccess restricted capability. To add access to the file system you will need to add the following to your Package.appxmanifest:

<Package xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities" ... >

Under the Capabilities section add the broadFileSystemAccess capability:

<Capabilities>
    <rescap:Capability Name="broadFileSystemAccess" />
</Capabilities>

🤖 Android

The bugsplat-unity plugin supports crash reporting for native C++ crashes on Android via Crashpad. To configure crash reporting for Android, set the UseNativeCrashReportingForAndroid and UploadDebugSymbolsForAndroid properties to true on the BugSplatManager instance.

You'll also need to configure the scripting backend to use IL2CPP, and target ARM64 (ARMV7a is not supported)

When you build your app for Android, be sure to set Create symbols.zip to Debugging

🍎 iOS

The bugsplat-unity plugin supports crash reporting for native C++ crashes on iOS via bugsplat-ios. To configure crash reporting for iOS, set the UseNativeCrashReportingForIos and UploadDebugSymbolsForIos properties to true on the BugSplatManager instance.

🧩 API

The following API methods are available to help you customize BugSplat to fit your needs.

BugSplatManager

Setting
Description

DontDestroyManagerOnSceneLoad

Should the BugSplat Manager persist through scene loads?

RegisterLogMessageRecieved

Register a callback function and allow BugSplat to capture instances of LogType.Exception.

BugSplat Options

Option
Description

Database

The name of your BugSplat database.

Application

The name of your BugSplat application. Defaults to Application.productName if no value is set.

Version

The version of your BugSplat application. Defaults to Application.version if no value is set.

Description

A default description that can be overridden by call to Post.

Email

A default email that can be overridden by call to Post.

Key

A default key that can be overridden by call to Post.

Notes

A default general purpose field that can be overridden by call to post

User

A default user that can be overridden by call to Post

CaptureEditorLog

Should BugSplat upload Editor.log when Post is called

CapturePlayerLog

Should BugSplat upload Player.log when Post is called

CaptureScreenshots

Should BugSplat a screenshot and upload it when Post is called

PostExceptionsInEditor

Should BugSplat upload exceptions when in editor

PersistentDataFileAttachmentPaths

Paths to files (relative to Application.persistentDataPath) to upload with each report

ShouldPostException

Settable guard function that is called before each BugSplat report is posted

SymbolUploadClientId

SymbolUploadClientSecret

🧑‍💻 Contributing

Click Play and click or tap one of the buttons to send an error report to BugSplat. To view the error report, navigate to the BugSplat and ensure you have selected the correct database.

Navigate to the page, and click the value in the ID column to see the details of your report, including the call stack, log file, and screenshot of your app when the error occurred.

If you're using BugSplatOptions and BugSplatManager, BugSplat automatically configures an Application.logMessageReceived handler that will post reports when it encounters a log message of type Exception. You can also extend your BugSplat integration and , , , and from native crashes.

Next, pass a callback to bugsplat.Post. In the callback handler add code to open the support response in the user's browser. A full example can be seen in .

BugSplat Support Response Page

More information on support responses can be found .

BugSplat can be configured to upload Windows minidumps created by the UnityCrashHandler. BugSplat will automatically pull Unity Player symbols from the . If your game contains Native Windows C++ plugins, .dll and .pdb files in the Assets/Plugins/x86 and Assets/Plugins/x86_64 folders will be uploaded by BugSplat's PostBuild script and used in symbolication.

To enable the uploading of plugin symbols, generate an OAuth2 Client ID and Client Secret on the BugSplat page. Add your Client ID and Client Secret to the BugSplatOptions object you generated in the section. Once configured, plugins will be uploaded automatically the next time you build your project.

We found that restricted capabilities were required in order to generate minidumps. Please see this Microsoft that describes how to configure your system to generate minidumps for UWP native crashes.

Finally, ensure that your application has access to the file system. The following is a snippet illustrating where this is set for our sample:

An OAuth2 Client ID value used for uploading generated via BugSplat's page

An OAuth2 Client Secret value used for uploading generated via BugSplat's page

BugSplat ❤️s open source! If you feel that this package can be improved, please open an . If you have an awesome new feature you'd like to implement, we'd love to merge your . You can also send us an , join us on , or message us via the in-app chat on .

📌
🎮
Dashboard
Crashes
customize report metadata
report exceptions in try/catch blocks
prevent repeated reports
upload windows minidumps
ErrorGenerator.cs
here
Unity Symbol Server
Integrations
Configuration
document
my-unity-crasher
Issue
Pull Request
email
Discord
bugsplat.com
symbol files
Integrations
symbol files
Integrations
OpenUPM
repository
here
here
usage
Importing the Sample
Finding the Sample
Configuring BugSplat
Running the Sample
BugSplat Crash Page
BugSplat Manager
BugSplat Create Options
BugSplat Options
BugSplat Manager Configured
Unity file system access
Android Player Settings
Android Build Settings