UE plugin documentation update (#8164)

Co-authored-by: Liza Mock <[email protected]>
Co-authored-by: Shana Matthews <[email protected]>

src/platform-includes/configuration/config-intro/unreal.mdx

@@ -4,6 +4,6 @@ The UE layer self-initializes through the use of the [UGameInstance](https://doc
 
 <Note>
 
-Not all options can be used on all platforms.
+Different options won't always be compatible with all platforms. Be sure to read the UE editor notices specifying which platforms the specific option works with.
 
 </Note>

src/platform-includes/getting-started-install/unreal.mdx

@@ -1,14 +1,30 @@
 The Unreal Engine (UE) SDK is officially supported for the three latest UE versions. However, it is likely to be compatible with older engine versions as well depending on the specific features and functionality that you need.
 
-To build the SDK, download the latest sources from the [Releases page](https://github.com/getsentry/sentry-unreal/releases) and place it in the project's `Plugins` directory. On the next project launch, UE will prompt to build Sentry module.
+To install the SDK, download the most up-to-date sources from the [Releases page](https://github.com/getsentry/sentry-unreal/releases) and add them to your project's `Plugins` directory. On the next project launch, UE will prompt you to build the Sentry module.
 
 <Note>
 
 Currently, this method is available only for C++ UE projects. Blueprint projects can be converted to a C++ one by adding an empty class using the editor.
 
 </Note>
 
-After the successful build, in the editor navigate to the **Settings > Plugins > Code Plugins** menu and check whether the Sentry plugin is enabled:
+<Note>
+
+The [Releases page](https://github.com/getsentry/sentry-unreal/releases) provides two plugin packages: `github` and `marketplace`. The key difference between the two is the crash capturing backend, which is used under the hood on Windows.
+
+We recommend using the `github` version which uses `Crashpad`, an out-of-proc handler that sends the crash report right away. The `marketplace` version relies on `Breakpad`, an in-proc handler which requires the UE application or game to be relaunched in order to send the crash report to Sentry.
+
+</Note>
+
+Alternatively, the Sentry SDK can be downloaded via the [standard installation process](https://docs.unrealengine.com/5.2/en-US/working-with-plugins-in-unreal-engine/#installingpluginsfromtheunrealenginemarketplace) from its UE Marketplace page within the Epic Games Launcher.
+
+<Note>
+
+This method is recommended only for Blueprint UE projects. If you already have a C++ UE project or don't mind converting an existing Blueprint UE project to a C++ one, consider downloading the plugin from GitHub instead.
+
+</Note>
+
+To make sure the Sentry plugin has been enabled after installation has been completed, go to the editor and navigate to the **Settings > Plugins > Code Plugins** menu and check for the installation.
 
 ![Sentry window](unreal_plugins_window.png)
 

src/platform-includes/getting-started-primer/unreal.mdx

@@ -12,6 +12,6 @@ Unreal Engine SDK builds on top of other Sentry SDKs and extends them with Unrea
 
 <Alert level="warning">
 
-[Crash Reporter Client](/platforms/unreal/configuration/setup-crashreporter/) has to be configured in order to capture crashes on Windows automatically with UE 5.1 or older. Starting from UE 5.2, the provided API allows you to switch between default and third-party crash-handling solutions, so this step isn't required.
+To automatically capture crashes on Windows with UE 5.1 or older, you have to configure the [Crash Reporter Client](/platforms/unreal/configuration/setup-crashreporter/). Starting from UE 5.2, the provided API allows you to switch between default (CRC) and third-party (Sentry) crash-handling solutions, so the CRC configuration step isn't required. The two are mutually exclusive and can't be used simultaneously.
 
 </Alert>

src/platforms/unreal/configuration/debug-symbols.mdx

@@ -6,7 +6,7 @@ redirect_from:
 description: "Learn how the Unreal Engine SDK handles debug symbols upload."
 ---
 
-Sentry requires [debug information files](/platforms/unreal/data-management/debug-files/) to symbolicate crashes. The Unreal Engine SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). This is done automatically, so running the `sentry-cli` manually isn't required. The symbol upload happens during the execution of `PostBuildSteps`, as specified in the `Sentry.uplugin` file. The `sentry-cli` executables for Windows, macOS, and Linux are included as part of the Unreal Engine SDK package.
+Sentry requires [debug information files](/platforms/unreal/data-management/debug-files/) to symbolicate crashes. The Unreal Engine SDK provides an automated upload functionality for those symbol files that rely on the [sentry-cli](/product/cli/). This is done automatically, so running the `sentry-cli` manually isn't required. The symbol upload happens during the execution of `PostBuildSteps`, as specified in the `Sentry.uplugin` file. The `sentry-cli` executables for Windows, macOS, and Linux are included as part of the Unreal Engine SDK package. They can also be downloaded manually via the settings menu if the plugin was installed from the UE Marketplace.
 
 <Note>
 
@@ -16,6 +16,12 @@ For Android, debug symbols upload is handled by [Sentry Android Gradle Plugin](/
 
 The automated debug symbols upload is disabled by default and requires configuration. To configure it, navigate to **Project Settings > Plugins > Sentry**, then enter the [Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/), Organization Slug, and Project Name. Note, that the Unreal Engine SDK automatically creates a `sentry.properties` file at the root of your project directory to store the configuration. This configuration file should **never** be made publicly available.
 
+<Note>
+
+You must configure which build configurations, target types, and platforms Sentry will upload debug symbols for in the "Misc" section of the plugin settings.
+
+</Note>
+
 ![The Unreal Engine debug symbols upload configuration](unreal-debug-symbols.png)
 
 ### Manual Upload Using sentry-cli

src/platforms/unreal/configuration/setup-crashreporter.mdx

@@ -7,60 +7,54 @@ redirect_from:
 ---
 
 Installation of a Sentry SDK is not required in order to capture the crashes of your
-UE4 application or game. Sentry supports the _UE4 Crash Reporter_.
+Unreal Engine application or game, because Sentry supports the _UE Crash Reporter_.
 
-To integrate your UE4 game or application with Sentry, the following steps are required:
+To integrate your UE game or application with Sentry, the following steps are required:
 
-1. Include the _UE4 Crash Reporter_ to your game or application.
+1. Include the _UE Crash Reporter_ in your game or application.
 2. Include Debug information in the crash reports.
 3. Add the Unreal Engine Endpoint to the relevant configuration file.
-4. Upload your games symbols so Sentry can display function names and line numbers.
-5. Optionally enable Event Attachments for your Sentry project.
+4. Upload your games' symbols so Sentry can display function names and line numbers.
+5. Optionally, enable Event Attachments for your Sentry project.
 
 Below we'll break down each step in detail.
 
-## UE4 Crash reporter
+## UE Crash Reporter
 
-The UE4 Crash Reporter is provided out of the box by Epic Games. It is able to collect relevant
+The UE Crash Reporter is provided out of the box by Epic Games. It is able to collect relevant
 information about the crash and send it to a service like Sentry to process.
 
 Adding it to your game means that in case a crash happens, the following dialog is displayed
 to the user:
 
-![The UE4 Crash Reporter](ue4-crash-reporter.png)
+![The UE Crash Reporter](ue-crash-reporter.png)
 
-### Include the UE4 Crash Reporter
+### Using the UE Crash Reporter on Windows
+
+The UE Crash Reporter works if the Sentry SDK is installed. Sentry SDK can help with configuring the UE Crash Reporter, uploading debug symbols, and enriching crash reports with custom data. **Starting from UE 5.2** users have to choose between the two available crash capturing mechanisms - the UE Crash Reporter or the `sentry-native` library that's integrated into the Sentry plugin. By default, the `sentry-native` library is used instead of the UE Crash Reporter. (See "Enable automatic crash capturing (Windows, UE 5.2+)" in the plugin settings.) The two solutions are mutually exclusive and can't be used simultaneously.
+
+### Include the UE Crash Reporter
 
 You can add the _Crash Reporter Client_ to your game in your _Project Settings_.
 
 The simplest way is to search the option: `Crash Reporter`:
 
-![Include UE4 Crash Reporter](ue4-include-crash-reporter.png)
+![Include UE Crash Reporter](ue-include-crash-reporter.png)
 
 The option is located under _Project > Packaging_ menu, then select _show advanced_ followed by
 checking the box for: `Include Crash Reporter`.
 
-## Debug information
+## Debug Information
 
-To get the most out of Sentry, crash reports are required to include debug information.
+To get the most out of captured crash reports [debug symbols](#upload-debug-symbols) need to be uploaded to Sentry.
 In order for Sentry to be able to process the crash report and translate
 memory addresses to meaningful information like function names, module names
-and line numbers, the crash itself must include debug information and also, [symbols need
-to be uploaded to Sentry](#upload-debug-symbols).
-
-### Include Debug Information
-
-![Include Debug Files](ue4-include-debug-files.png)
-
-The option is also located under _Project > Packaging_ menu, then select _show advanced_ followed by
-checking the box for: `Include Debug Files`.
+and line numbers, the crash itself must be associated with the corresponding debug information first.
 
 ## Configure the Crash Reporter Endpoint
 
-Now that the _Crash Reporter_ and _Debug Files_ are included, UE4 needs to know where to send the
-crash. For that, we add the Sentry _Unreal Engine Endpoint_ from the _Client Keys_ settings page to game's configuration file. This will
-include which project within Sentry you want to see the crashes arriving in real time.
-That's accomplished by configuring the `CrashReportClient` in the _DefaultEngine.ini_ file. Changing the engine is necessary for this to work.
+Now that the _Crash Reporter_ and _Debug Files_ are included, UE needs to know where to send the
+crash. For that, we need to add the Sentry _Unreal Engine Endpoint_ from the _Client Keys_ settings page to the game's configuration file. This will include whichever project within Sentry you want to see real-time crashes for. That's accomplished by configuring the `CrashReportClient` in the _DefaultEngine.ini_ file. You'll need to change the engine to do this to work.
 
 Edit the file:
 
@@ -74,17 +68,17 @@ CrashReportClientVersion=1.0
 DataRouterUrl="___UNREAL_URL___"
 ```
 
-<Alert level="info" title="Note">
+<Note>
 
 If a `[CrashReportClient]` section already exists, simply changing the value of `DataRouterUrl`
 is enough.
 
-</Alert>
+</Note>
 
 Alternatively, the endpoint can be added automatically to the _DefaultEngine.ini_ file
 by using the Sentry configuration window.
 
-![The UE4 Crash Reporter settings](ue4-crash-reporter-settings.png)
+![The UE Crash Reporter settings](ue-crash-reporter-settings.png)
 
 Navigate to the editor's menu **Project Settings > Plugins > Sentry**, set the Sentry _Unreal Engine Endpoint_ in the corresponding input field, and click the **Update global settings** button to apply changes. The default endpoint value can be restored by clicking the **Reset** button once the _Crash Reporter_ is no longer needed.
 
@@ -134,6 +128,18 @@ void ConfigureCrashReporter()
 You need to call the `ConfigureCrashReporter` some time after your game
 starts. Any [event attribute](https://develop.sentry.dev/sdk/event-payloads/) can be set.
 
+<Note>
+
+You should configure Crash Reporter attributes before initializing the Sentry SDK. Otherwise, some information may get overwritten and lost.
+
+</Note>
+
+<Note>
+
+The Sentry SDK provides an API which allows you to set Crash Reporter attributes as well.
+
+</Note>
+
 Depending on the version of Unreal Engine you are using, you may have to
 add JSON support to the build script (`MyProject.build.cs`):
 
@@ -148,6 +154,12 @@ symbolicated stack traces, you need to upload _Debug Information Files_
 (sometimes also referred to as _Debug Symbols_ or just _Symbols_). We recommend
 uploading debug information during your build or release process.
 
+<Note>
+
+The Sentry SDK can handle uploading [debug symbols](/platforms/unreal/configuration/debug-symbols/) automatically at build time.
+
+</Note>
+
 For all libraries where you'd like to receive symbolication, **you need
 to provide debug information**. This includes dependencies and operating system
 libraries.
@@ -163,12 +175,12 @@ see [Debug Information Files](/workflow/debug-files/).
 
 ## Size Limits
 
-Event ingestion imposes limits on the size of UE4 crash reports. These limits
+Event ingestion imposes size limits on UE crash reports. These limits
 are subject to future change and defined currently as:
 
 - _20MB_ for a compressed request
 - _100MB_ for the full crash report after decompression
 
-## Issues With The Crash Reporter
+## Issues With the Crash Reporter
 
-For tips on troubleshooting the UE4 Crash Reporter, [check out this thread in Sentry's forum](https://forum.sentry.io/t/unreal-engine-crash-reporter-cant-get-it-to-work/7643) where community members have delved into potential solutions.
+Check out this community-generated [thread in Sentry's forum](https://forum.sentry.io/t/unreal-engine-crash-reporter-cant-get-it-to-work/7643) for UE Crash Reporter troubleshooting tips and solutions.