BugSplat's com.bugsplat.unity package provides crash and exception reporting for Unity projects. BugSplat provides you with invaluable insight into the issues tripping up your users. Our Unity integration collects screenshots, log files, exceptions, and Windows minidumps so that you can fix bugs and deliver a better user experience.
Before you proceed, please make sure you have completed the following checklist:
BugSplat's com.bugsplat.unity package can be added to your project via OpenUPM or a URL to our git repository.
Information on installing OpenUPM can be found here. After installing OpenUPM, run the following command to add BugSplat to your project.
openupm add com.bugsplat.unityInformation on adding a Unity package via a git URL can be found here.
https://github.com/BugSplat-Git/bugsplat-unity.gitTip
BugSplat recommends building with the IL2CPP backend for the best crash reporting experience. For more information please see the Player Settings section.
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 usage instructions.
To import the sample, click the caret 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.
Note
The sample's UI labels use TextMeshPro. If the button text appears blank, import TMP Essentials via Window > TextMeshPro > Import TMP Essential Resources. TextMeshPro can't render without its default font asset, which is imported per-project and can't be bundled in the sample.
Click Play and run a scenario from the Crash Scenarios menu to send an error report to BugSplat. Scenarios are grouped by the mechanism that captures them, and the menu is platform-aware — each platform lists only what it can capture. Native scenarios are disabled in the editor and need a built player; see the sample README for the full scenario matrix. To view the error report, navigate to the BugSplat Dashboard and ensure you have selected the correct database.
Navigate to the Crashes 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.
For best results, BugSplat recommends building with the IL2CPP backend. The Mono backend is supported, but has several limitations. With IL2CPP, BugSplat can capture fully symbolicated C# exception traces in production, as well as native crashes that contain call stacks mapped back to their original C# function names, file names, and line numbers.
To optimize your game for crash reporting, open Player Settings (Edit > Player Settings). Navigate to the Configuration section. For Scripting Backend choose IL2CPP and for IL2CPP StackTrace Information choose Method Name, File Name, and Line Number.
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.
Exceptions thrown in the editor are not uploaded by default, so play mode errors never reach the database you ship with. Check PostExceptionsInEditor on the options asset (or set bugsplat.PostExceptionsInEditor = true in code) while you verify your integration.
Finally, provide a valid BugSplatOptions to BugSplatManager.
What BugSplat captures on each platform. Setup for each one is covered in Android, iOS, macOS, and Windows.
| Capability | Windows | macOS | iOS | Android | Linux | WebGL |
|---|---|---|---|---|---|---|
| Managed C# exceptions | Yes | Yes | Yes | Yes | Yes | Yes |
| Native crashes | Yes (Mono or IL2CPP) | Yes (IL2CPP only) | Yes | Yes | No | No |
| Hang / ANR reporting | Yes (opt-in) | No | Yes | Yes (Android 11+) | No | No |
| Offline retry of native reports | Yes | Yes | Yes | Yes | n/a | n/a |
User feedback (PostFeedback) |
Yes | Yes | Yes | Yes | Yes | No |
| Automatic symbol upload | Yes (from a Windows editor) | Yes | Yes | Yes | No | No |
- Managed C# exceptions are captured on every platform through Unity's log callbacks — including background threads — and posted over HTTPS. WebGL uses a separate reporter that cannot attach log files or screenshots.
- Native crashes require the matching option on your
BugSplatOptionsasset:UseNativeCrashReportingForWindows,UseNativeCrashReportingForMac,UseNativeCrashReportingForIos, orUseNativeCrashReportingForAndroid. Linux and WebGL have no native reporter and fall back to managed exception reporting alone. Every native reporter is compiled out of the editor, so play mode exercises the managed rows only. - Hang / ANR reporting is opt-in on Windows through
WindowsHangDetectionTimeoutMs(0, disabled, by default) and automatic on iOS and Android once native crash reporting is enabled. Android ANRs additionally need Android 11 (API level 30) at runtime. macOS has no hang detection. - Offline retry covers native reports only: they are written to disk when the crash happens and uploaded on a later launch, so being offline at crash time does not lose the report. Managed exception posts are never persisted — if that upload fails, the report is gone.
- User feedback is posted with
bugsplat.PostFeedback. WebGL has no feedback client and logs an error instead. - Automatic symbol upload runs as a post-build step and needs symbol upload credentials. Windows uploads
.pdb,.dll, and.exefiles only when the player is built from a Windows editor with Copy PDB files enabled. macOS uploads dSYMs whenUploadDebugSymbolsForMacis set, unless the build is an Xcode project export. iOS adds an Xcode build phase that uploads dSYMs during the Xcode build whenUploadDebugSymbolsForIosis set. Android uploads the generated symbols archive whenUploadDebugSymbolsForAndroidis set, and skips it when Export Project is enabled or Debug Symbols is None. Linux and WebGL have no symbol upload step.
Two things that don't fit the table: Post(FileInfo minidump) works on every platform except WebGL, where it logs that it isn't implemented and returns without uploading; and IL2CPP's LineNumberMappings.json, which maps generated C++ frames back to C# names, files, and line numbers, is uploaded on Windows, macOS, and iOS only — the Android symbol upload sends native .so symbols alone.
Everything above gets you reporting. These pages cover the rest.
| Page | What's in it |
|---|---|
| Usage | Adding metadata, try/catch reporting, throttling, background thread and unobserved task exceptions, support responses |
| Android | Native crash reporting via Crashpad, player settings, symbols.zip, ANR reporting |
| iOS | Native crash reporting via PLCrashReporter, dSYM upload, hang detection |
| macOS | Native crash reporting via PLCrashReporter, dSYM upload |
| Windows | Native crash reporting, plugin and IL2CPP symbols, hang detection, Windows Error Reporting |
| API | BugSplatManager settings, every BugSplatOptions field, Player.log and privacy, native crash report attachments |
| Symbol Upload | Credentials, where they resolve from, environment variables |
| Migrating from 4.x | What 5.0.0 removed and renamed, and what to change |
BugSplat ❤️s open source! If you feel that this package can be improved, please open an Issue. If you have an awesome new feature you'd like to implement, we'd love to merge your Pull Request. You can also send us an email, join us on Discord, or message us via the in-app chat on bugsplat.com.