docs(unity): sync the page with the 5.0.0 SDK

[bobbyg603]

Important

Stacked on #327. Base is docs/unity-windows-native-crash-reporting, not master — GitHub retargets this once #327 merges. Review the two-dot diff to see only this PR's changes.

Draft: documents unreleased behavior. Hold until BugSplat-Git/bugsplat-unity#225 merges and 5.0.0 ships.

What

Brings the Unity page in line with the 5.0.0 SDK. The page still described a 4.x integration: whole feature areas were missing, and several passages documented an API that 5.0.0 removes.

Source of truth was the bugsplat-unity repo — the documentation set on #227 (README.md plus Documentation~/*.md), the 5.0.0 section of CHANGELOG.md, and the sample README — with every claim checked against Runtime/BugSplat.cs, Runtime/Client/BugSplatOptions.cs, Runtime/Manager/BugSplatManager.cs, Editor/PostBuild.cs, and the two Apple bridges. Where the SDK's own docs and its source disagreed, the source won; see Contradictions.

Section by section

Added — 🧭 Platform Support (new, after Configuration). The capability matrix across Windows, macOS, iOS, Android, Linux, and WebGL, with a note per row explaining what gates it. Closes with the two facts that don't fit a table (Post(FileInfo) everywhere but WebGL; LineNumberMappings.json on Windows, macOS, and iOS only) and the Utils.ForceCrash caveat — it routes through Unity's own pipeline and is not captured by the native reporters on iOS, macOS, or Android.

Added — Background Thread Exceptions and Unobserved Task Exceptions (Usage). Both are new capture paths in 5.0.0, both on by default, both requiring Register Log Message Received. Covers the 64-slot bound and drop warning, the main-thread deduplication, the GC-driven timing of unobserved tasks, and why BugSplat deliberately does not call SetObserved().

Added — Attaching Files to Native Crash Reports (Usage). The page had zero coverage of this. A native crash is captured and uploaded by the platform's own crash reporter, which never sees bugsplat.Attachments or ReportPostOptions.AdditionalAttachments, so a reader had no way to learn that native reports use a separate mechanism. Documents AttachNativeLogFile, the new DetachNativeLogFile, the additive-and-idempotent guarantee, full-path resolution (case-insensitive on Windows), thread safety, the per-platform support table (Windows/macOS/iOS multiple, Android a no-op), and how it interoperates with CapturePlayerLog. Notes that iOS support is new — the bridge was a no-op stub before the vendored bugsplat-apple 3.5.0.

Added — Player Log and Privacy (Usage). Why CapturePlayerLog defaults on, that Player.log records paths containing the OS username, how to opt out, the WebGL exception, and that pre-5.0.0 options assets keep their serialized value.

Added — 🔑 Symbol Upload (new section). Credentials are per database and never stored in the project; resolution order (SYMBOL_UPLOAD_CLIENT_ID / SYMBOL_UPLOAD_CLIENT_SECRET, then ~/.bugsplat/credentials/<database>.sh), the three editor menu items, what happens when credentials are missing, and the environment variable table.

Added — 🚚 Migrating from 4.x (new section). Removed post methods, the crash-folder minidump flow, the credential fields and renamed environment variables, the stale iOS build phase (with the rotate-your-secret warning), the Attributes type change, the namespace moves and BugSplatRef becoming internal, awaited Post coroutines, and main-thread callbacks.

Corrected — CapturePlayerLog. The options table said only "Should BugSplat upload Player.log when Post is called". It also controls whether Player.log is attached to native crash reports on the platforms whose native reporter supports attachments, and has since earlier 5.0.0 work. Corrected in the options table, in the Windows section bullet #327 added, and in the macOS section.

Corrected — stale options table rows. Removed SymbolUploadClientId and SymbolUploadClientSecret (deleted from BugSplatOptions in 5.0.0) and ShouldPostException (never a field on the asset — moved to a note, matching the SDK README). Added the rows that were missing entirely: LogFileMaxSizeMB, Attributes, UseNativeCrashReportingForIos, UploadDebugSymbolsForIos, UseNativeCrashReportingForAndroid, UploadDebugSymbolsForAndroid. The BugSplatManager table gained CaptureExceptionsOnBackgroundThreads and CaptureUnobservedTaskExceptions.

Corrected — Windows Symbols. It told readers to put the Client ID and Secret on the BugSplatOptions object and named BUGSPLAT_CLIENT_ID / BUGSPLAT_CLIENT_SECRET. All three are gone in 5.0.0; the section now points at 🔑 Symbol Upload.

Corrected — Android. UseNativeCrashReportingForAndroid named explicitly as the ANR gate, and ARM64 described as the only tested ABI (the bundled .aar ships armeabi-v7a and x86_64 too, untested and unsupported) rather than "ARMV7a is not supported".

Corrected — iOS. Added PLCrashReporter/Mach exception handling, that BugSplat disables Unity's built-in crash reporter during the Xcode export to avoid conflicting with it, and LineNumberMappings.json upload for IL2CPP.

Corrected — stale sample references. The Android and iOS sections pointed at the sample's "Hang / ANR button", which no longer exists — the sample is now a platform-aware Crash Scenarios menu with a HANG section.

Corrected — five broken links. Player Settings, usage, Configuration, and the two metadata/try-catch links pointed at github.com/BugSPlat-Git/bugsplat-unity#… anchors that stopped resolving when the README was split into Documentation~. All now use in-page anchors.

Added inside #327's Windows section (gaps, not duplication): the Unregister WER Handler menu item, the two diagnostic paths to check when a report doesn't arrive (%TEMP%\BugSplat\… and %LOCALAPPDATA%\CrashDumps), and the note that BugSplat locks SetUnhandledExceptionFilter so other middleware cannot install a top-level filter after it.

Deliberately left alone

• Windows native crash reporting and WER — docs(unity): document native Windows crash reporting and WER #327's material. Untouched apart from the three additions listed above and the CapturePlayerLog correction to one bullet.
• PostExceptionsInEditor — docs(unity): PostExceptionsInEditor defaults to false in 5.0.0 #332 owns both the Configuration paragraph and the options-table row. Its row is left byte-identical here so the two stack cleanly, which does mean that row still reads "Should BugSplat upload exceptions when in editor" until docs(unity): PostExceptionsInEditor defaults to false in 5.0.0 #332 lands. The Configuration section is likewise untouched.
• The Sample section — being revised separately for the new scenario menu.

The options table keeps its existing column widths so untouched rows, including #327's and #332's, stay byte-identical. The BugSplatManager table was re-padded because the new setting names are longer than the old column.

Contradictions found

One place where the SDK's own docs and its source disagree, resolved in favor of the source:

• README.md on Docs audit: introduction/development/web-services/api/company.md — 3 content findings #227 says the Windows symbol upload happens "only when the player is built from a Windows editor with Copy PDB files enabled". Editor/PostBuild.cs only skips the upload when it can read that copyPDBFiles is off, and it can only read that from a Windows editor — from any other editor it logs a warning and uploads anyway. The page describes the actual behavior. Worth fixing in the SDK README too.

Two smaller drifts, not blocking:

• The XML doc on BugSplat.CapturePlayerLog says the native attach/detach applies to "Windows and macOS". AddNativeAttachment has an iOS branch as of Docs audit: introduction/development/using-the-app.md — 4 content findings, 11 outdated screenshots #225, so iOS is included. The page says "platforms whose native reporter supports attachments" rather than naming a stale list.
• Documentation~/api.md on Docs audit: introduction/development/web-services/api/company.md — 3 content findings #227 lists CaptureExceptionsOnBackgroundThreads in the BugSplatManager table but omits CaptureUnobservedTaskExceptions, which exists in BugSplatManager.cs and defaults to true. Both are documented here.

Not verifiable from the repo

Player.log attachment to native iOS reports goes through Application.consoleLogPath, and whether Unity returns a usable path for that on an iOS player was not something I could confirm from source. The page avoids claiming it specifically, saying "platforms whose native reporter supports attachments" instead. Worth a device check before release.

🤖 Generated with Claude Code