feat: support for unity as a library on Android

CHANGELOG.md

@@ -8,12 +8,13 @@
 
 ### Fixes
 
+- App hang detection no longer reports a false app hang after the game moves to the background. It now stays paused while the game is in the background or out of focus. ([#2895](https://github.com/getsentry/sentry-unity/pull/2895))
 - The Linux native SDK now loads on distros with older glibc versions, such as Ubuntu 22.04 and Debian 12. ([#2894](https://github.com/getsentry/sentry-unity/pull/2894))
 - Attaching a screenshot no longer stalls the main thread. Unless `SetBeforeSendScreenshot` is set, the frame gets read back from the GPU asynchronously and encoded on a background thread. ([#2835](https://github.com/getsentry/sentry-unity/pull/2835))
 
 ### Features
 
-- Added experimental support for Unity as a Library on iOS. With `IosNativeInitializationType` set to `NativeInitializationType.External`, the game attaches to the sentry-cocoa SDK that the app already started instead of bundling and starting its own. Native crashes carry the game's context and breadcrumbs, C# events and logs use the app's release, environment, user, and trace, the game's transactions join the app's trace, and the game's debug symbols are still uploaded automatically. ([#2885](https://github.com/getsentry/sentry-unity/pull/2885))
+- Added experimental support for Unity as a Library on Android and iOS. With `AndroidNativeInitializationType` or `IosNativeInitializationType` set to `NativeInitializationType.External`, the game attaches to the sentry-android or sentry-cocoa SDK that the app already started instead of bundling and starting its own. On Android, when the game runs in its own process, it starts sentry-android there and continues the app's trace. Native crashes carry the game's context and breadcrumbs, C# events and logs use the app's release, environment, user, and trace, the game's transactions join the app's trace, and the game's debug symbols are still uploaded automatically. ([#2885](https://github.com/getsentry/sentry-unity/pull/2885), [#2895](https://github.com/getsentry/sentry-unity/pull/2895))
 - The SDK now supports Linux ARM64 dedicated servers (Unity 6000.3 and newer, IL2CPP). The native SDK for both backends ships for `x86_64` and `ARM64`, and the build picks the one matching the player. ([#2894](https://github.com/getsentry/sentry-unity/pull/2894))
 
 ### Dependencies

docs/agent-guides/platform-android.md

@@ -12,6 +12,7 @@
 - Runtime initialization writes `io.sentry.auto-init=false`; C# initializes the Java SDK later.
 - Build-time initialization writes options to the Android manifest and lets Java auto-initialize.
 - Runtime option changes cannot alter build-time initialization behavior.
+- External initialization (Unity as a Library, experimental): the export ships no SDK, writes no manifest entries (they would merge into the app's), and keeps the ProGuard consumer rules. At runtime the game attaches if sentry-android is enabled in its process (no user, environment, or trace sync, no close, no NDK app-hang heartbeat). In a secondary process (e.g. `:Unity`), where the app didn't initialize it, the game initializes it from the Unity options with its own cache directory (`cache/sentry-<process>`), so it doesn't take over the main process's session and persisted scope, and with ANR and tombstone reporting off, since the main process's SDK reports the exits of all the app's processes. There it continues the main process's trace, read from that SDK's persisted scope (`cache/sentry/<dsn hash>/.scope-cache/trace.json`) at start and on resume, and turns off its own trace generation. The symbol upload task goes into `unityLibrary/build.gradle` and runs after `merge<Variant>JniLibFolders`, since the app never builds `launcher`. In the main process without an SDK, native support is skipped. The process name comes from `Application.getProcessName` (API 28+) or `/proc/self/cmdline` below. C# sessions are off and the app's release and environment are used unless set.
 
 ## Export Processing
 

package-dev/Plugins/Android/proguard-sentry-unity.pro

@@ -6,6 +6,14 @@
 -keep class io.sentry.SentryLevel { *; }
 -keep class io.sentry.SentryOptions { *; }
 -keep class io.sentry.Hub { *; }
+-keep class io.sentry.IHub { *; }
+-keep class io.sentry.IScopes { *; }
+-keep class io.sentry.HubScopesWrapper { *; }
+-keep class io.sentry.SentryTraceHeader { *; }
+-keep class io.sentry.BaggageHeader { *; }
+-keep class io.sentry.SpanContext { *; }
+-keep class io.sentry.ISerializer { *; }
+-keep class io.sentry.JsonSerializer { *; }
 -keep class io.sentry.Breadcrumb { *; }
 -keep class io.sentry.Scope { *; }
 -keep class io.sentry.ScopeCallback { *; }

src/Sentry.Unity.Android/ExternalAndroidJavaScopeObserver.cs

@@ -0,0 +1,31 @@
+namespace Sentry.Unity.Android;
+
+/// <summary>
+/// Scope sync for <see cref="NativeInitializationType.External"/>. The game follows the app's trace. When attached to
+/// the app's SDK, the app also owns the user. In its own process, the game's SDK needs it.
+/// </summary>
+internal sealed class ExternalAndroidJavaScopeObserver : AndroidJavaScopeObserver
+{
+    private readonly bool _isAttached;
+
+    public ExternalAndroidJavaScopeObserver(SentryOptions options, ISentryJava sentryJava, bool isAttached)
+        : base(options, sentryJava) => _isAttached = isAttached;
+
+    public override void SetUserImpl(SentryUser user)
+    {
+        if (!_isAttached)
+        {
+            base.SetUserImpl(user);
+        }
+    }
+
+    public override void UnsetUserImpl()
+    {
+        if (!_isAttached)
+        {
+            base.UnsetUserImpl();
+        }
+    }
+
+    public override void SetTraceImpl(SentryId traceId, SpanId spanId) { }
+}