Unity
Last updated
Last updated
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.
Information on adding a Unity package via a git URL can be found here.
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 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.
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 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.
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
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 customize report metadata, report exceptions in try/catch blocks, prevent repeated reports, and upload windows minidumps from native crashes.
First, find your instance of BugSplat
. The following is an example of how to find an instance of BugSplat
via BugSplatManager
:
You can extend BugSplat
by setting the following properties:
You can use the Notes
field to capture arbitrary data such as system information:
Exceptions can be sent to BugSplat in a try/catch block by calling Post
.
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.
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:
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.
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 ErrorGenerator.cs.
When an exception occurs, a page similar to the following will open in the user's browser on Windows, macOS, and Linux.
More information on support responses can be found here.
BugSplat can be configured to upload Windows minidumps created by the UnityCrashHandler
. BugSplat will automatically pull Unity Player symbols from the Unity Symbol Server. 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 Integrations page. Add your Client ID and Client Secret to the BugSplatOptions
object you generated in the Configuration section. Once configured, plugins will be uploaded automatically the next time you build your project.
The methods PostCrash
, PostMostRecentCrash
, and PostAllCrashes
can be used to upload minidumps to BugSplat. We recommend running PostMostRecentCrash
when your game launches.
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.
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.
Reporting exceptions, crashes, and uploading log files requires the Internet (Client)
capability.
We found that restricted capabilities were required in order to generate minidumps. Please see this Microsoft document that describes how to configure your system to generate minidumps for UWP native crashes.
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
:
Under the Capabilities
section add the broadFileSystemAccess
capability:
Finally, ensure that your application has access to the file system. The following is a snippet illustrating where this is set for our my-unity-crasher sample:
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
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.
The following API methods are available to help you customize BugSplat to fit your needs.
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. |
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. |
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 | An OAuth2 Client ID value used for uploading symbol files generated via BugSplat's Integrations page |
SymbolUploadClientSecret | An OAuth2 Client Secret value used for uploading symbol files generated via BugSplat's Integrations page |
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.