From a450d7b788beca9820e955ae19ae2bf6ff160bf3 Mon Sep 17 00:00:00 2001
From: Adam Brown <adam.brown@sentry.io>
Date: Tue, 8 Sep 2026 16:45:05 +0200
Subject: [PATCH] docs(android): Clarify manual init guidance

Warn Android users to initialize the SDK once in Application.onCreate when using manual setup.

Call out Activity lifecycle methods as the wrong place for normal startup initialization, since they may run multiple times and make init-related behavior harder to reason about.

Refs JAVA-722
Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
---
 docs/platforms/android/manual-setup/index.mdx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/platforms/android/manual-setup/index.mdx b/docs/platforms/android/manual-setup/index.mdx
index 4a98a3c7261f16..6de84aa4c2bd94 100644
--- a/docs/platforms/android/manual-setup/index.mdx
+++ b/docs/platforms/android/manual-setup/index.mdx
@@ -80,7 +80,7 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
   <meta-data android:name="io.sentry.session-replay.on-error-sample-rate" android:value="1.0" />
   <meta-data android:name="io.sentry.session-replay.session-sample-rate" android:value="0.1" />
 
-  <!-- If your application has strict PII requirements we recommend using the Canvas screenshot strategy. 
+  <!-- If your application has strict PII requirements we recommend using the Canvas screenshot strategy.
   See the Android Session Replay documentation for details: https://docs.sentry.io/platforms/android/session-replay/#screenshot-strategy -->
   <!-- <meta-data android:name="io.sentry.session-replay.screenshot-strategy" android:value="canvas" /> -->
 
@@ -124,7 +124,7 @@ Or, to completely remove the merging of the `ContentProvider`:
 
 The next step is to initialize the SDK directly in your code.
 
-The SDK can catch errors and crashes only after you've initialized it. For that reason, we recommend calling `SentryAndroid.init` in your Application class as soon as the application is created. If you don't already have a custom Application class, [check out the official docs on how to create one](https://developer.android.com/reference/android/app/Application).
+The SDK can catch errors and crashes only after you've initialized it. For that reason, we recommend calling `SentryAndroid.init` once in your Application class as soon as the application is created. Avoid calling it from `Activity.onCreate()` or other activity lifecycle methods. If you don't already have a custom Application class, [check out the official docs on how to create one](https://developer.android.com/reference/android/app/Application).
 
 Configuration options will be loaded from the manifest so that you don't need to have the static properties in your code. In the `init` method, you can provide a callback that will modify the configuration and also register new options.
 
@@ -243,4 +243,3 @@ public class MyApplication extends Application {
 ```
 
 Additional options can be found <PlatformLink to="/configuration/options/">on our dedicated options page</PlatformLink>.
-