Unreal marketplace limitations (#12076)

* Create installation-recommendations.md * Update installation-recommendations.md * Update index.mdx * Update installation-recommendations.md * Update installation-recommendations.md * Update index.mdx * Update installation-recommendations.md * Update docs/platforms/unreal/installation/installation-recommendations.md * Moving GitHub releases to the top * Moving installation to the main page * Update docs/platforms/unreal/index.mdx * Update docs/platforms/unreal/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/platforms/unreal/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/platforms/unreal/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/platforms/unreal/index.mdx Co-authored-by: Liza Mock <[email protected]> --------- Co-authored-by: Ivan Tustanivskyi <[email protected]> Co-authored-by: Liza Mock <[email protected]>
getsentry · Dec 10, 2024 · 4a1e509 · 4a1e509
1 parent d238ec7
commit 4a1e509
Showing 1 changed file with 47 additions and 8 deletions.
diff --git a/docs/platforms/unreal/index.mdx b/docs/platforms/unreal/index.mdx
@@ -34,10 +34,39 @@ Don't already have an account and Sentry project established? Head over to [sent
 
 ## Install
 
-Sentry captures data by using an SDK within your application’s runtime.
+Sentry captures data by using an SDK within your application’s runtime. 
 
 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.
 
+There are three common ways to install an SDK to use with Unreal Engine:
+1. Install from the [Epic Games Fab](https://www.fab.com/) ([formerly known as the marketplace](https://www.unrealengine.com/en-US/blog/fab-epics-new-unified-content-marketplace-launches-today))
+2. Download a pre-built SDK that you install (for example, from a [GitHub Releases page](https://github.com/getsentry/sentry-unreal/releases))
+3. Clone and build the SDK yourself and install
+
+While you can use any of the three methods to install Sentry, each has its own limitations, as described below.
+
+### Overview of SDK Versions
+
+The table below highlights some key differences between different versions of the SDK:
+
+| Feature                    | __GitHub Releases__* | Fab                 | Build Yourself |
+|----------------------------|----------------------|---------------------|----------------|
+| Supported engine versions  | 4.27 and newer       | 5.1 and newer       | 4.27 and newer |
+| Supported UE project types | C++ only             | Blueprint and C++   | C++ only       |
+| Backend (Windows)          | Crashpad             | Breakpad            | Crashpad       |
+| `on_crash` hook (Windows)  | Supported            | Not supported       | Supported      |
+| Sentry CLI **              | Included             | Manual download     | Included       |
+
+Legend:  
+`*`: Recommended version of the SDK  
+`**`: Sentry CLI is a standalone tool that the plugin uses under the hood to automatically upload debug information files upon game build completion.  
+
+### Installing from GitHub Releases (Recommended)
+
+The [GitHub 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, because it 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 before any crash reports can be sent to Sentry.
+
 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 and SentryEditor modules.
 
 <Note>
@@ -46,22 +75,32 @@ Currently, this method is available only for C++ UE projects. Blueprint projects
 
 </Note>
 
-<Note>
+### Installing from Fab
 
-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.
+Sentry SDK can be downloaded via the [standard installation process](https://dev.epicgames.com/documentation/en-us/unreal-engine/working-with-plugins-in-unreal-engine#installingpluginsfromtheunrealenginemarketplace) from its [Epic Games Fab page](https://www.fab.com/listings/eaa89d9d-8d39-450c-b75f-acee010890a2).
 
-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 reports to Sentry.
+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>
+### Build Yourself
 
-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](https://www.unrealengine.com/marketplace/en-US/product/sentry-01) page within the Epic Games Launcher.
+To get started, we recommend cloning the [Unreal SDK repository](https://github.com/getsentry/sentry-unreal) and running the initialization script:
 
-<Note>
+* `./scripts/init.sh` on macOS/Linux
+* `./scripts/init-win.ps1` on Windows
 
-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>
+Initialization scripts require [GitHub CLI](https://cli.github.com/) to be installed.
+</Note>
 
+<Note>
+If the initialization script fails due to errors on Windows, check your PowerShell version by printing the built-in variable `$PSVersionTable`. If the version is `5.x`, upgrading to a newer version of [PowerShell](https://github.com/powershell/powershell) may resolve these errors.
 </Note>
 
+This script links the checked out version of the plugin (the [plugin-dev](https://github.com/getsentry/sentry-unreal/tree/b67076ad5dc419d46b4be70a0bd6e64c2357a82d/plugin-dev) directory) to the [sample app](https://github.com/getsentry/sentry-unreal/tree/b67076ad5dc419d46b4be70a0bd6e64c2357a82d/sample) and downloads the latest builds of native SDKs from our GitHub CI.
+
+After successful initialization, copy the contents of the `plugin-dev` directory to `<your_project_root>/Plugins/Sentry`. This will allow you to use Sentry in your Unreal Engine project.
+
+### Confirm Installation
 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](./img/unreal_plugins_window.png)