docs(unity): Fix native support and platform docs by bitsandfoxes · Pull Request #20416 · getsentry/sentry-docs

bitsandfoxes · 2026-11-03T13:58:49Z

DESCRIBE YOUR PR

Corrects the Unity native support and platform docs against the sentry-unity 4.13.0 source: which platforms get native crash reporting, what each one needs, and what reaches native crash reports.

Stacked on #20414, which adds the option entries this PR links to. Its base is that branch, so the diff shows only this PR's changes.

Supported Platforms table on the Native Support page: native crashes, native SDK or backend, and requirements per platform, with the minimum Unity version, dedicated servers, the supported consoles and the platforms the SDK doesn't support. visionOS and UWP run on a best-effort basis.
Consoles report native crashes; the "work in progress" note is removed.
Android native support needs IL2CPP, and so does the default Cocoa backend on macOS; the experimental Native backend works with Mono.
Scope Sync section: what the SDK copies to the native SDKs, and what doesn't reach native crashes (custom contexts, attachments on iOS and macOS with Cocoa, the parts the app's SDK owns with Unity as a Library, and NDK scope sync turned off). The Attachments and Context pages link to it.
Windows: every file the build copies next to the player (crashpad_handler.exe, crashpad_wer.dll, sentry-native.dll; with the experimental Native backend sentry-crash.exe, sentry-wer.dll, sentry-native.dll), x64 and x86, and the experimental Native backend. macOS: the experimental Native backend. NativeHandlerPath and DisableFileWrite.
Game Consoles: Xbox needs PersistentLocalStorage in MicrosoftGame.config; Switch needs TemporaryStorageSize in the .nmeta, and runs without file writes, automatic session tracking or IL2CPP line numbers.
Minidumps: "Windows, Linux, and macOS with the Native backend" on the Native Support, Attachments and Store Minidumps pages.
iOS: main.mm and SentryObjC.xcframework in the native support and troubleshooting text.
Known limitations: why WebGL has no IL2CPP line numbers.

The Unity quick start (docs/platforms/unity/index.mdx, open in #20012) names only crashpad_handler.exe as the file to ship with a Windows build; it needs the same three-file list.

Pages to check on the preview:

/platforms/unity/native-support/
/platforms/unity/game-consoles/
/platforms/unity/enriching-events/attachments/
/platforms/unity/enriching-events/context/

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

Urgent deadline (GA date, etc.): YYYY-MM-DD
Other deadline: YYYY-MM-DD
No deadline: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

🤖 Generated with Claude Code

vercel · 2026-11-03T13:58:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sentry-docs	Ready	Preview	Nov 13, 2026 10:48pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Nov 13, 2026 10:48pm UTC

coolguyzone

Looks good, thanks for updating!

JoshuaMoelans

lgtm, small nit on native backend not being experimental (but if it's still considered experimental in the Unity-use-case, I think it's fine leaving it as-is)

JoshuaMoelans · 2026-11-13T13:25:15Z

-On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the crashpad backend. Windows native crashes are automatically captured through minidumps. To upload these to Sentry, the SDK copies the `crashpad_handler.exe` to the build output directory at the end of the build process. This executable must be included when shipping your game.
+On Windows, the Unity SDK includes the [Native SDK](/platforms/native/) with the Crashpad backend, for both 64-bit (x64) and 32-bit (x86) players. Windows native crashes are captured through minidumps. At the end of the build, the SDK copies `crashpad_handler.exe`, `crashpad_wer.dll`, and `sentry-native.dll` next to the player. Include all three files when you ship your game.
+
+With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game.


Suggested change

With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game.

With the Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game.

JoshuaMoelans · 2026-11-13T13:25:18Z


+Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms.
+
+With an out-of-process crash handler (Crashpad on Windows, or the experimental Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in <PlatformLink to="/configuration/options/">Options</PlatformLink>.


backend isn't experimental since getsentry/sentry-native#1919

Suggested change

With an out-of-process crash handler (Crashpad on Windows, or the experimental Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in <PlatformLink to="/configuration/options/">Options</PlatformLink>.

With an out-of-process crash handler (Crashpad on Windows, or the Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in <PlatformLink to="/configuration/options/">Options</PlatformLink>.

JoshuaMoelans · 2026-11-13T13:26:43Z

-The Native Support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process.
+By default, native support on macOS relies on the [macOS SDK](/platforms/apple/guides/macos/). Stackwalking happens in process. This Cocoa backend needs IL2CPP. With Mono, the SDK captures C# errors only.
+
+With the experimental Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono.


Suggested change

With the experimental Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono.

With the Native backend, which you can select with `options.Experimental.MacosBackend = MacosBackend.Native`, the SDK uses the [Native SDK](/platforms/native/) instead. It uploads crashes right away through the out-of-process `sentry-crash` handler, which the build copies next to the player, and it works with both IL2CPP and Mono.

Add a supported platforms table and a scope sync section to the Native Support page, and describe the Android, iOS, Windows and macOS native options and backends. Native crashes on consoles are supported, so drop the "work in progress" note. Document the Xbox PersistentLocalStorage requirement and the Nintendo Switch limits on the Game Consoles page. Fix the minidump platform list, the iOS main.mm and SentryObjC names, and the WebGL line number note.

Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>

codeowner-assignment Bot requested a review from a team November 3, 2026 13:59

github-actions Bot added the Priority: Normal Docs review has no urgent deadline label Nov 3, 2026

vercel Bot deployed to Preview – sentry-docs November 3, 2026 14:05

View deployment

bitsandfoxes mentioned this pull request Nov 3, 2026

docs(unity): Fix debug symbol upload docs #20418

Open

1 of 6 tasks

bitsandfoxes marked this pull request as ready for review November 3, 2026 14:30

codeowner-assignment Bot requested a review from a team November 3, 2026 14:30

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from f7a6597 to 6aa06e1 Compare November 3, 2026 14:41

vercel Bot deployed to Preview – sentry-docs November 3, 2026 14:49

View deployment

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from 6aa06e1 to 92d507c Compare November 3, 2026 16:08

vercel Bot deployed to Preview – sentry-docs November 3, 2026 16:15

View deployment

coolguyzone approved these changes Nov 5, 2026

View reviewed changes

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from 92d507c to f25e488 Compare November 13, 2026 12:23

codeowner-assignment Bot requested a review from a team November 13, 2026 12:23

vercel Bot deployed to Preview – sentry-docs November 13, 2026 12:24

View deployment

bitsandfoxes added this pull request to stack #20792 November 13, 2026 13:07

JoshuaMoelans approved these changes Nov 13, 2026

View reviewed changes

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from f25e488 to d734098 Compare November 13, 2026 16:05

codeowner-assignment Bot requested a review from a team November 13, 2026 16:05

vercel Bot deployed to Preview – sentry-docs November 13, 2026 16:13

View deployment

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from d734098 to 092eb13 Compare November 13, 2026 16:33

vercel Bot deployed to Preview – sentry-docs November 13, 2026 16:39

View deployment

vercel Bot deployed to Preview – sentry-docs November 13, 2026 16:47

View deployment

Base automatically changed from fix/unity-docs-undocumented-options to master November 13, 2026 22:43

bitsandfoxes added 5 commits November 13, 2026 23:43

docs(unity): Address review of native support docs

a3bdbe0

docs(unity): State the IL2CPP requirement for Android native support

1dee809

docs(unity): Move the visionOS and UWP note out of the table

e9989e5

docs(unity): Scope NativeHandlerPath to out-of-process handlers

4628b2c

Apply suggestions from code review

17d7c94

Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>

bitsandfoxes force-pushed the fix/unity-docs-native-platforms branch from 3c9fb99 to 17d7c94 Compare November 13, 2026 22:43

vercel Bot deployed to Preview – sentry-docs November 13, 2026 22:48

View deployment

bitsandfoxes merged commit 80d61ae into master Nov 13, 2026
28 checks passed

bitsandfoxes deleted the fix/unity-docs-native-platforms branch November 13, 2026 22:56

Navigation Menu

Repository navigation

docs(unity): Fix native support and platform docs - #20416

docs(unity): Fix native support and platform docs#20416
bitsandfoxes merged 6 commits into
masterfrom
fix/unity-docs-native-platforms

bitsandfoxes commented Nov 3, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Nov 3, 2026 •

edited

Loading

Uh oh!

coolguyzone left a comment

Uh oh!

JoshuaMoelans left a comment

Uh oh!

JoshuaMoelans Nov 13, 2026

Uh oh!

JoshuaMoelans Nov 13, 2026

Uh oh!

JoshuaMoelans Nov 13, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	With the experimental Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game.
	With the Native backend, which you can select with `options.Experimental.WindowsBackend = WindowsBackend.Native`, the SDK uploads crashes right away through the out-of-process `sentry-crash.exe` handler. The build copies `sentry-crash.exe`, `sentry-wer.dll`, and `sentry-native.dll` next to the player instead. Include all three files when you ship your game.


		Native support on Windows, Linux, and macOS with the Native backend writes files to disk. If you set `DisableFileWrite`, the SDK turns native support off on these platforms.

		With an out-of-process crash handler (Crashpad on Windows, or the experimental Native backend), `NativeHandlerPath` sets where the SDK looks for the handler executable. By default, it's next to the player executable. Learn more in <PlatformLink to="/configuration/options/">Options</PlatformLink>.

Conversation

bitsandfoxes commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

JoshuaMoelans left a comment

Choose a reason for hiding this comment

Uh oh!

JoshuaMoelans Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaMoelans Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaMoelans Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bitsandfoxes commented Nov 3, 2026 •

edited

Loading

vercel Bot commented Nov 3, 2026 •

edited

Loading