{"id":25836074,"url":"https://github.com/bugsplat-git/bugsplat-unity","last_synced_at":"2025-07-28T06:03:32.564Z","repository":{"id":39877166,"uuid":"362548521","full_name":"BugSplat-Git/bugsplat-unity","owner":"BugSplat-Git","description":"🎮💥👾 BugSplat crash and error reporting for Unity games","archived":false,"fork":false,"pushed_at":"2025-07-21T21:47:05.000Z","size":117191,"stargazers_count":9,"open_issues_count":15,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-21T23:25:23.369Z","etag":null,"topics":["bugsplat","crash","development","error","game","hacktoberfest","reporting","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BugSplat-Git.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-28T17:09:05.000Z","updated_at":"2025-07-21T21:47:08.000Z","dependencies_parsed_at":"2025-07-21T23:28:39.155Z","dependency_job_id":null,"html_url":"https://github.com/BugSplat-Git/bugsplat-unity","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/BugSplat-Git/bugsplat-unity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BugSplat-Git%2Fbugsplat-unity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BugSplat-Git%2Fbugsplat-unity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BugSplat-Git%2Fbugsplat-unity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BugSplat-Git%2Fbugsplat-unity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BugSplat-Git","download_url":"https://codeload.github.com/BugSplat-Git/bugsplat-unity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BugSplat-Git%2Fbugsplat-unity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267470063,"owners_count":24092352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bugsplat","crash","development","error","game","hacktoberfest","reporting","unity"],"created_at":"2025-03-01T01:39:02.087Z","updated_at":"2025-07-28T06:03:32.551Z","avatar_url":"https://github.com/BugSplat-Git.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![bugsplat-github-banner-basic-outline](https://user-images.githubusercontent.com/20464226/149019306-3186103c-5315-4dad-a499-4fd1df408475.png)](https://bugsplat.com)\n\u003cbr/\u003e\n# \u003cdiv align=\"center\"\u003eBugSplat\u003c/div\u003e \n### **\u003cdiv align=\"center\"\u003eCrash and error reporting built for busy developers.\u003c/div\u003e**\n\u003cdiv align=\"center\"\u003e\n    \u003ca href=\"https://twitter.com/BugSplatCo\"\u003e\n        \u003cimg alt=\"Follow @bugsplatco on Twitter\" src=\"https://img.shields.io/twitter/follow/bugsplatco?label=Follow%20BugSplat\u0026style=social\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://discord.gg/K4KjjRV5ve\"\u003e\n        \u003cimg alt=\"Join BugSplat on Discord\" src=\"https://img.shields.io/discord/664965194799251487?label=Join%20Discord\u0026logo=Discord\u0026style=social\"\u003e\n    \u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://openupm.com/packages/com.bugsplat.unity/\"\u003e\n        \u003cimg alt=\"BugSplatUnity on OpenUPM\" src=\"https://img.shields.io/npm/v/com.bugsplat.unity?label=openupm\u0026registry_uri=https://package.openupm.com\"\u003e\n    \u003c/a\u003e\n\u003c/div\u003e\n\n## 👋 Introduction\n\nBugSplat'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.\n\nBefore you proceed, please make sure you have completed the following checklist:\n* [Sign Up](https://app.bugsplat.com/v2/sign-up) as a new BugSplat user\n* [Log In](https://app.bugsplat.com/cognito/login) to your account\n\n## 🏗 Installation\n\nBugSplat's `com.bugsplat.unity` package can be added to your project via [OpenUPM](https://openupm.com/packages/com.bugsplat.unity/) or a URL to our git [repository](https://github.com/BugSplat-Git/bugsplat-unity.git).\n\n### OpenUPM\nInformation on installing OpenUPM can be found [here](https://openupm.com). After installing OpenUPM, run the following command to add BugSplat to your project.\n\n```sh\nopenupm add com.bugsplat.unity\n```\n\n### Git\nInformation on adding a Unity package via a git URL can be found [here](https://docs.unity3d.com/Manual/upm-ui-giturl.html).\n\n```sh\nhttps://github.com/BugSplat-Git/bugsplat-unity.git\n```\n\n## 🧑‍🏫 Sample\n\n\u003e [!TIP]\n\u003e BugSplat recommends building with the IL2CPP backend for the best crash reporting experience. For more information please see the [Player Settings](#-player-settings ) section.\n\nAfter 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](#usage) instructions.\n\nTo 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.\n\n![Importing the Sample](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/b7a39388-eb76-413a-a92f-72fd39c9a7d6)\n\n\nIn the Project Assets browser, open the **Sample** scene from `Samples \u003e BugSplat \u003e Version \u003e my-unity-crasher \u003e Scenes`.\n\nNext, select `Samples \u003e BugSplat \u003e Version \u003e my-unity-crasher` to reveal the **BugSplatOptions** object. Click BugSplatOptions and replace the database value with your BugSplat database.\n\n![Finding the Sample](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/ba9aa64a-1d85-45a8-b11f-565520c30bcf)\n\n![Configuring BugSplat](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/a6250cea-a4da-44a8-b6cb-ff2467b0d978)\n\nClick **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](https://app.bugsplat.com/v2/dashboard) and ensure you have selected the correct database.\n\n![Running the Sample](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/4418b736-dc88-496a-ada6-a27ad19032f1)\n\nNavigate to the [Crashes](https://app.bugsplat.com/v2/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.\n\n![BugSplat Crash Page](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/f108d7e9-ee90-4a09-a7b4-8a9b5d764942)\n\n## 🧰 Player Settings\n\nFor 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.\n\nTo optimize your game for crash reporting, open `Player Settings` (`Edit \u003e 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`.\n\n![Unity Player Settings](https://github.com/user-attachments/assets/ed459d7e-8580-4e8d-b6aa-386ecaa51a56)\n\n## ⚙️ Configuration\n\nBugSplat'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.\n\n![BugSplat Manager](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/ef5240a6-9676-43c6-a482-51216cb34401)\n\n`BugSplatManager` needs to be initialized with a `BugSplatOptions` serialized object. A new instance of `BugSplatOptions` can be created through the Asset Create menu.\n\n![BugSplat Create Options](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/9ec402d1-4b8a-49cf-96e9-00d951717771)\n\nConfigure fields as appropriate. Note that if Application or Version are left empty, `BugSplat` will  default these values to `Application.productName` and `Application.version`, respectively.\n\n![BugSplat Options](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/be7ee217-9170-48b4-b780-fcb47e221f77)\n\nFinally, provide a valid `BugSplatOptions` to `BugSplatManager`. \n\n![BugSplat Manager Configured](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/67bed7b5-e2a9-4f52-b5bb-bdc8eebd35a0)\n\n## ⌨️ Usage\n\nIf 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](#adding-metadata), [report exceptions in try/catch blocks](#trycatch-reporting), [prevent repeated reports](#preventing-repeated-reports), and [upload windows minidumps](#windows) from native crashes.\n\n### Adding Metadata\n\nFirst, find your instance of `BugSplat`. The following is an example of how to find an instance of `BugSplat` via `BugSplatManager`:\n\n```cs\nvar bugsplat = FindObjectOfType\u003cBugSplatManager\u003e().BugSplat;\n```\n\nYou can extend `BugSplat` by setting the following properties:\n\n```cs\nbugsplat.Attachments.Add(new FileInfo(\"/path/to/attachment.txt\"));\nbugsplat.Description = \"description!\";\nbugsplat.Email = \"fred@bugsplat.com\";\nbugsplat.Key = \"key!\";\nbugsplat.Notes = \"notes!\";\nbugsplat.User = \"Fred\";\nbugsplat.CaptureEditorLog = true;\nbugsplat.CapturePlayerLog = false;\nbugsplat.CaptureScreenshots = true;\n```\n\nYou can use the `Notes` field to capture arbitrary data such as system information:\n\n```cs\nvoid Start()\n{\n    bugsplat = FindObjectOfType\u003cBugSplatManager\u003e().BugSplat;\n    bugsplat.Notes = GetSystemInfo();\n}\n\nprivate string GetSystemInfo()\n{\n    var info = new Dictionary\u003cstring, string\u003e();\n    info.Add(\"OS\", SystemInfo.operatingSystem);\n    info.Add(\"CPU\", SystemInfo.processorType);\n    info.Add(\"MEMORY\", $\"{SystemInfo.systemMemorySize} MB\");\n    info.Add(\"GPU\", SystemInfo.graphicsDeviceName);\n    info.Add(\"GPU MEMORY\", $\"{SystemInfo.graphicsMemorySize} MB\");\n\n    var sections = info.Select(section =\u003e $\"{section.Key}: {section.Value}\");\n    return string.Join(Environment.NewLine, sections);\n}\n```\n\n### Try/Catch Reporting\n\nExceptions can be sent to BugSplat in a try/catch block by calling `Post`.\n\n```cs\ntry\n{\n    throw new Exception(\"BugSplat rocks!\");\n}\ncatch (Exception ex)\n{\n    StartCoroutine(bugsplat.Post(ex));\n}\n```\n\nThe 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.\n\n```cs\nvar options = new ReportPostOptions()\n{\n    Description = \"a new description\",\n    Email = \"barney@bugsplat.com\",\n    Key = \"a new key!\",\n    Notes = \"some new notes!\",\n    User = \"Barney\"\n};\n\noptions.AdditionalAttachments.Add(new FileInfo(\"/path/to/additional.txt\"));\n\nstatic void callback()\n{\n    Debug.Log($\"Exception post callback!\");\n};\n\nStartCoroutine(bugsplat.Post(ex, options, callback));\n```\n\n### Preventing Repeated Reports\n\nBy default, BugSplat prevents reports from being sent at a rate greater than 1 per every 3 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\u003cException, bool\u003e` value. Be sure your new implementation can handle a null value for `Exception`!\n\nThe following example demonstrates how you could implement your own time-based report throttling mechanism:\n\n```cs\nvar lastPost = new DateTime(0);\n\nbugsplat.ShouldPostException = (ex) =\u003e\n{\n    var now = DateTime.Now;\n\n    if (now - lastPost \u003c TimeSpan.FromSeconds(3))\n    {\n        Debug.LogWarning(\"ShouldPostException returns false. Skipping BugSplat report...\");\n        return false;\n    }\n\n    Debug.Log(\"ShouldPostException returns true. Posting BugSplat report...\");\n    lastPost = now;\n\n    return true;\n};\n```\n\n### Windows Minidumps (Crashes)\n\nBugSplat can be configured to upload Windows minidumps created by the `UnityCrashHandler`. BugSplat will automatically pull Unity Player symbols from the [Unity Symbol Server](https://docs.unity3d.com/Manual/WindowsDebugging.html).\n\nThe methods `PostCrash`, `PostMostRecentCrash`, and `PostAllCrashes` can be used to upload minidumps to BugSplat. We recommend running `PostAllCrashes` when your game launches.\n\n```cs\nvoid Start()\n{\n    bugsplat = FindObjectOfType\u003cBugSplatManager\u003e().BugSplat;\n    StartCoroutine(bugsplat.PostAllCrashes());\n}\n\n```\n\nEach 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.\n\nYou can generate a test crash on Windows with any of the following methods.\n\n```cs\nUtils.ForceCrash(ForcedCrashCategory.Abort);\nUtils.ForceCrash(ForcedCrashCategory.AccessViolation);\nUtils.ForceCrash(ForcedCrashCategory.FatalError);\nUtils.ForceCrash(ForcedCrashCategory.PureVirtualFunction);\n```\n\n### Windows Symbols\n\nTo enable the uploading of plugin symbols, generate an OAuth2 Client ID and Client Secret on the BugSplat [Integrations](https://app.bugsplat.com/v2/settings/database/integrations) page. Add your Client ID and Client Secret to the `BugSplatOptions` object you generated in the [Configuration](#⚙️-configuration) section. 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.\n\nFor IL2CPP builds, BugSplat will also upload `LineNumberMappings.json`. Line mappings allow BugSplat to replace generated C++ function names, file names, and line numbers with their original C# equivalents.\n\n### Support Response\n\nBugSplat 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.\n\nNext, 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](https://github.com/BugSplat-Git/bugsplat-unity/blob/main/Samples~/my-unity-crasher/Scripts/ErrorGenerator.cs).\n\n```cs\nprivate string infoUrl = \"\";\n\npublic void Event_CatchExceptionThenPostNewBugSplat()\n{\n    try\n    {\n        GenerateSampleStackFramesAndThrow();\n    }\n    catch (Exception ex)\n    {\n        var options = new ReportPostOptions()\n        {\n            Description = \"a new description\"\n        };\n\n        StartCoroutine(bugsplat.Post(ex, options, ExceptionCallback));\n    }\n}\n\nvoid ExceptionCallback(ExceptionReporterPostResult result)\n{\n    UnityEngine.Debug.Log($\"Exception post callback result: {result.Message}\");\n\n    if (result.Response == null) {\n        return;\n    }\n\n    UnityEngine.Debug.Log($\"BugSplat Status: {result.Response.status}\");\n    UnityEngine.Debug.Log($\"BugSplat Crash ID: {result.Response.crashId}\");\n    UnityEngine.Debug.Log($\"BugSplat Support URL: {result.Response.infoUrl}\");\n\n    infoUrl = result.Response.infoUrl;\n}\n\nprivate void OpenUrl(string url)\n{\n    var escaped = url.Replace(\"?\", \"\\\\?\").Replace(\"\u0026\", \"\\\\\u0026\").Replace(\" \", \"%20\").Replace(\"!\", \"\\\\!\");\n\n#if UNITY_STANDALONE_WIN || UNITY_EDITOR_WIN || UNITY_WSA\n    Process.Start(url);\n#elif UNITY_STANDALONE_OSX || UNITY_EDITOR_OSX\n    Process.Start(\"open\", escaped);\n#elif UNITY_STANDALONE_LINUX || UNITY_EDITOR_LINUX\n    Process.Start(\"xdg-open\", escaped);\n#else\n    UnityEngine.Debug.Log($\"OpenUrl unsupported platform: {Application.platform}\");\n#endif\n}\n```\n\nWhen an exception occurs, a page similar to the following will open in the user's browser on Windows, macOS, and Linux.\n\n\u003cimg width=\"1086\" alt=\"image\" src=\"https://github.com/user-attachments/assets/3a3d6f82-e3bf-42bc-ae7f-582ba35cd499\"\u003e\n\nMore information on support responses can be found [here](https://docs.bugsplat.com/introduction/production/setting-up-custom-support-responses).\n\n## 🤖 Android\n\nThe 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.\n\nYou'll also need to configure the scripting backend to use IL2CPP, and target ARM64 (ARMV7a is not supported)\n\n![Android Player Settings](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/9ec8f5b7-8dfd-43db-84e0-7e7d1229324a)\n\nWhen you build your app for Android, be sure to set `Create symbols.zip` to `Debugging`\n\n![Android Build Settings](https://github.com/BugSplat-Git/bugsplat-unity/assets/2646053/0181f2a8-8fb2-4745-b336-3e7f210aa55e)\n\n## 🍎 iOS\n\nThe 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.\n\n## 🧩 API\n\nThe following API methods are available to help you customize BugSplat to fit your needs.\n\n### BugSplatManager\n\n| Setting | Description |\n| --------------- | --------------- |\n| DontDestroyManagerOnSceneLoad | Should the BugSplat Manager persist through scene loads? | \n| RegisterLogMessageRecieved | Register a callback function and allow BugSplat to capture instances of LogType.Exception.|\n\n### BugSplat Options\n\n| Option | Description |\n| --------------- | --------------- |\n| Database  | The name of your BugSplat database. | \n| Application| The name of your BugSplat application. Defaults to Application.productName if no value is set.|\n| Version | The version of your BugSplat application. Defaults to Application.version if no value is set.|\n| Description | A default description that can be overridden by call to Post.|\n| Email | A default email that can be overridden by call to Post.|\n| Key | A default key that can be overridden by call to Post.|\n| Notes | A default general purpose field that can be overridden by call to post |\n| User | A default user that can be overridden by call to Post |\n| CaptureEditorLog| Should BugSplat upload Editor.log when Post is called|\n| CapturePlayerLog| Should BugSplat upload Player.log when Post is called |\n| CaptureScreenshots | Should BugSplat a screenshot and upload it when Post is called |\n| PostExceptionsInEditor | Should BugSplat upload exceptions when in editor |\n| PersistentDataFileAttachmentPaths |  Paths to files (relative to Application.persistentDataPath) to upload with each report |\n| ShouldPostException | Settable guard function that is called before each BugSplat report is posted |\n| SymbolUploadClientId | An OAuth2 Client ID value used for uploading [symbol files](https://docs.bugsplat.com/introduction/development/working-with-symbol-files) generated via BugSplat's [Integrations](https://app.bugsplat.com/v2/settings/database/integrations) page\n| SymbolUploadClientSecret | An OAuth2 Client Secret value used for uploading [symbol files](https://docs.bugsplat.com/introduction/development/working-with-symbol-files) generated via BugSplat's [Integrations](https://app.bugsplat.com/v2/settings/database/integrations) page\n\n## 🧑‍💻 Contributing\n\nBugSplat ❤️s open source! If you feel that this package can be improved, please open an [Issue](https://github.com/BugSplat-Git/bugsplat-unity/issues). If you have an awesome new feature you'd like to implement, we'd love to merge your [Pull Request](https://github.com/BugSplat-Git/bugsplat-unity/pulls). You can also send us an [email](mailto:support@bugsplat.com), join us on [Discord](https://discord.gg/K4KjjRV5ve), or message us via the in-app chat on [bugsplat.com](https://bugsplat.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugsplat-git%2Fbugsplat-unity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbugsplat-git%2Fbugsplat-unity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugsplat-git%2Fbugsplat-unity/lists"}