chore(samples-android): Add optional SAGP build mode (#5538)

Adds an optional useSagp flag to Android sample app builds that, when true, applies the Sentry Android Gradle Plugin. (Defaults to false, which matches existing build behavior.)

```
./gradlew :sentry-samples:sentry-samples-android:installDebug -PuseSagp=true
```

See the Android sample app README for more details.

Author: 0xadam-brown

sentry-samples/sentry-samples-android/README.md

@@ -0,0 +1,57 @@
+# Sentry Sample Android App
+
+Sample application demonstrating how to use the Sentry Android SDK, including core functionality (error reporting, tracing, session replay,
+profiling) and integrations (Compose, OkHttp, etc.).
+
+## How to run it?
+
+Install the app on your device or emulator:
+
+```
+./gradlew :sentry-samples:sentry-samples-android:installDebug
+```
+
+or simply open the project in Android Studio and run the `sentry-samples-android` configuration.
+
+You can also apply the [Sentry Android Gradle Plugin](https://github.com/getsentry/sentry-android-gradle-plugin) (SAGP) when building (not applied by default):
+
+```
+./gradlew :sentry-samples:sentry-samples-android:installDebug -PuseSagp=true
+```
+
+In Android Studio, add `useSagp=true` to `gradle.properties` or pass it as a Gradle project property.
+
+## Build modes
+
+### With or without SAGP
+
+The sample app can be built with or without the SAGP.
+
+| Gradle Property | Required                 | Purpose                                                                                                        |
+|-----------------|--------------------------|----------------------------------------------------------------------------------------------------------------|
+| `useSagp`       | No (defaults to `false`) | When `true`, apply SAGP when building the sample app. When false or absent, build the sample app without SAGP. |
+
+You can configure SAGP properties via the lambda passed to `extensions.configure<SentryPluginExtension>("sentry")` in the sample app's
+`build.gradle.kts` file.
+
+### Builds against your local sentry-java branch
+
+Regardless of `useSagp`, the sample always depends on sentry-java modules from this monorepo (e.g., `projects.sentryAndroid`). SAGP's SDK
+auto-installation is disabled, so the sample never pulls a separate SDK version from Maven. Local SDK changes in your branch are picked up
+directly.
+
+## Viewing SDK output
+
+### Locally
+
+Debug builds enable SDK debug logging, so captured envelopes are printed to logcat (tag `Sentry`):
+
+```
+adb logcat -s Sentry
+```
+
+### On Sentry UI
+
+By default, SDK output produced by the sample app appears under the [sentry-sdk test project](https://sentry-sdks.sentry.io/issues/?project=5428559).
+To redirect them to your own project, replace the test DSN (i.e., the `io.sentry.dsn` `meta-data` value in `src/main/AndroidManifest.xml`
+with your own.

sentry-samples/sentry-samples-android/build.gradle.kts

@@ -1,12 +1,44 @@
 import com.android.build.api.artifact.SingleArtifact
 import com.android.build.api.variant.impl.VariantImpl
+import io.sentry.android.gradle.extensions.InstrumentationFeature
+import io.sentry.android.gradle.extensions.SentryPluginExtension
 import org.apache.tools.ant.taskdefs.condition.Os
 import org.gradle.internal.extensions.stdlib.capitalized
 
 plugins {
   id("com.android.application")
   alias(libs.plugins.kotlin.android)
   alias(libs.plugins.kotlin.compose)
+  alias(libs.plugins.sentry) apply false
+}
+
+val useSagp =
+  providers.gradleProperty("useSagp").map { it.equals("true", ignoreCase = true) }.orElse(false)
+
+if (useSagp.get()) {
+  apply(plugin = "io.sentry.android.gradle")
+}
+
+plugins.withId("io.sentry.android.gradle") {
+  // Extension configs match non-SAGP builds. Update locally to test your feature.
+  extensions.configure<SentryPluginExtension>("sentry") {
+    autoInstallation.enabled.set(false)
+    includeProguardMapping.set(false)
+    includeDependenciesReport.set(false)
+    telemetry.set(false)
+    tracingInstrumentation {
+      features.set(
+        setOf(
+          InstrumentationFeature.COMPOSE,
+          InstrumentationFeature.DATABASE,
+          InstrumentationFeature.FILE_IO,
+          InstrumentationFeature.OKHTTP,
+        )
+      )
+      logcat.enabled.set(false)
+      appStart.enabled.set(false)
+    }
+  }
 }
 
 android {