diff --git a/docs/platforms/android/configuration/manual-init.mdx b/docs/platforms/android/configuration/manual-init.mdx deleted file mode 100644 index 14746fdac054c..0000000000000 --- a/docs/platforms/android/configuration/manual-init.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Manual Configuration -sidebar_order: 20 -description: "Learn how to initialize the SDK manually when you need to provide additional configuration." ---- - -## Manual Installation - -If you don't want the Sentry Gradle plugin to install the Sentry SDK automatically, you can define the dependency directly in the `build.gradle` file of your app module. - -```groovy {filename:app/build.gradle} -dependencies { - implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '4.2.0') }}' -} -``` - -```kotlin {filename:app/build.gradle.kts} -dependencies { - implementation("io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '4.2.0') }}") -} -``` - - - -The [NDK integration](/platforms/android/using-ndk/) comes packaged with the SDK and requires API level 16, though other levels are supported. If you're using multiple Sentry dependencies, you can add a [bill of materials](/platforms/android/configuration/bill-of-materials) to avoid specifying the version of each dependency. - - - -## Manual Initialization - -Initialize the SDK manually when you need to provide additional configuration to the SDK that cannot be specified in the manifest. - -To initialize the SDK manually, disable the auto initialization. You can do so by adding the following line into your manifest: - -```xml {filename:AndroidManifest.xml} - - - -``` - -Or, to completely remove the merging of the `ContentProvider`: - -```xml {filename:AndroidManifest.xml} - - - - - -``` - -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. So, we recommend calling `SentryAndroid.init` in the instance your Application class right after the application is created. If you don't have a custom Application class yet, [checkout 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. - - -```java -import io.sentry.SentryLevel; -import io.sentry.android.core.SentryAndroid; -import android.app.Application; - -public class MyApplication extends Application { - public void onCreate() { - super.onCreate(); - - SentryAndroid.init(this, options -> { - options.setDsn("___PUBLIC_DSN___"); - // Add a callback that will be used before the event is sent to Sentry. - // With this callback, you can modify the event or, when returning null, also discard the event. - options.setBeforeSend((event, hint) -> { - if (SentryLevel.DEBUG.equals(event.getLevel())) - return null; - else - return event; - }); - }); - } -} -``` - -```kotlin -import io.sentry.android.core.SentryAndroid -import io.sentry.SentryOptions.BeforeSendCallback -import io.sentry.Hint -import android.app.Application - -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - - SentryAndroid.init(this) { options -> - options.dsn = "___PUBLIC_DSN___" - // Add a callback that will be used before the event is sent to Sentry. - // With this callback, you can modify the event or, when returning null, also discard the event. - options.beforeSend = - BeforeSendCallback { event: SentryEvent, hint: Hint -> - if (SentryLevel.DEBUG == event.level) { - null - } else { - event - } - } - } - } -} -``` diff --git a/docs/platforms/android/integrations/apollo3/index.mdx b/docs/platforms/android/integrations/apollo3/index.mdx index 07092588a5efa..f349f0f22fd9d 100644 --- a/docs/platforms/android/integrations/apollo3/index.mdx +++ b/docs/platforms/android/integrations/apollo3/index.mdx @@ -172,7 +172,7 @@ Alternatively, you can customize the event and scrub the data yourself. ### Customize or Drop the Error Event -To customize or drop the error event, you'll need to do a [manual initialization](/platforms/android/configuration/manual-init/#manual-initialization) of the Sentry Android SDK. The captured error event can then be customized or dropped with a `BeforeSendCallback`: +To customize or drop the error event, you'll need to do a [manual initialization](/platforms/android/manual-setup/#configuration-via-sentryoptions) of the Sentry Android SDK. The captured error event can then be customized or dropped with a `BeforeSendCallback`: ```kotlin import io.sentry.android.core.SentryAndroid diff --git a/docs/platforms/android/integrations/fragment/index.mdx b/docs/platforms/android/integrations/fragment/index.mdx index d8b97a81d7ceb..19f4336e73c82 100644 --- a/docs/platforms/android/integrations/fragment/index.mdx +++ b/docs/platforms/android/integrations/fragment/index.mdx @@ -42,7 +42,7 @@ However, you can still override the default behaviour by adding your own instanc ### Install -To add the Fragment integration, [manually initialize](/platforms/android/configuration/manual-init/#manual-initialization) the Android SDK, then add the `sentry-android-fragment` dependency. Using Gradle: +To add the Fragment integration, [manually initialize](/platforms/android/manual-setup/#configuration-via-sentryoptions) the Android SDK, then add the `sentry-android-fragment` dependency. Using Gradle: ```groovy implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '5.1.0') }}' diff --git a/docs/platforms/android/integrations/jetpack-compose/index.mdx b/docs/platforms/android/integrations/jetpack-compose/index.mdx index 62d93d609505a..1c1111f5ceb13 100644 --- a/docs/platforms/android/integrations/jetpack-compose/index.mdx +++ b/docs/platforms/android/integrations/jetpack-compose/index.mdx @@ -101,7 +101,7 @@ This feature is disabled by default, but you can enable it the following ways. #### Using `SentryOptions` -If you initialize the SDK [manually as mentioned here](/platforms/android/configuration/manual-init/#manual-initialization), you can enable user interactions like this: +If you initialize the SDK [manually as mentioned here](/platforms/android/manual-setup/#configuration-via-sentryoptions), you can enable user interactions like this: ```kotlin {filename:MyApplication.kt} SentryAndroid.init(this) { options -> @@ -330,7 +330,7 @@ fun Second() { ## Customize the Recorded Breadcrumb/Transaction -By default, the Navigation integration captures route arguments as additional data on breadcrumbs and transactions. In case the arguments contain any PII data, you can strip it out by way of `BeforeBreadcrumbCallback` and `EventProcessor` respectively. To do that, [manually initialize](/platforms/android/configuration/manual-init/#manual-initialization) the SDK and add the following snippet: +By default, the Navigation integration captures route arguments as additional data on breadcrumbs and transactions. In case the arguments contain any PII data, you can strip it out by way of `BeforeBreadcrumbCallback` and `EventProcessor` respectively. To do that, [manually initialize](/platforms/android/manual-setup/#configuration-via-sentryoptions) the SDK and add the following snippet: ```kotlin import io.sentry.EventProcessor diff --git a/docs/platforms/android/integrations/ktor-client/index.mdx b/docs/platforms/android/integrations/ktor-client/index.mdx index 5b667569dcff7..8278b5ff0b4b7 100644 --- a/docs/platforms/android/integrations/ktor-client/index.mdx +++ b/docs/platforms/android/integrations/ktor-client/index.mdx @@ -155,7 +155,7 @@ Those events are searchable and you can set alerts on them if you use the `http. ### Customize or Drop the Error Event -To customize or drop the error event, you need to do a [manual initialization](/platforms/android/configuration/manual-init/#manual-initialization) of the Sentry Android SDK. +To customize or drop the error event, you need to do a [manual initialization](/platforms/android/manual-setup/#configuration-via-sentryoptions) of the Sentry Android SDK. The captured error event can be customized or dropped with a `BeforeSendCallback`: diff --git a/docs/platforms/android/integrations/navigation/index.mdx b/docs/platforms/android/integrations/navigation/index.mdx index 8e2f4470345b1..9f0bf065ed00d 100644 --- a/docs/platforms/android/integrations/navigation/index.mdx +++ b/docs/platforms/android/integrations/navigation/index.mdx @@ -123,7 +123,7 @@ class HomeFragment : Fragment() { ## Customize the Recorded Breadcrumb/Transaction -By default, the Navigation integration captures route arguments as additional data on breadcrumbs and transactions. In case the arguments contain any PII data, you can strip it out by way of `BeforeBreadcrumbCallback` and `EventProcessor` respectively. To do that, [manually initialize](/platforms/android/configuration/manual-init/#manual-initialization) the SDK and add the following snippet: +By default, the Navigation integration captures route arguments as additional data on breadcrumbs and transactions. In case the arguments contain any PII data, you can strip it out by way of `BeforeBreadcrumbCallback` and `EventProcessor` respectively. To do that, [manually initialize](/platforms/android/manual-setup/#configuration-via-sentryoptions) the SDK and add the following snippet: ```kotlin import io.sentry.EventProcessor diff --git a/docs/platforms/android/integrations/okhttp/index.mdx b/docs/platforms/android/integrations/okhttp/index.mdx index 8dd049424e68b..48db2a30ef16e 100644 --- a/docs/platforms/android/integrations/okhttp/index.mdx +++ b/docs/platforms/android/integrations/okhttp/index.mdx @@ -399,7 +399,7 @@ Those events are searchable and you can set alerts on them if you use the `http. ### Customize or Drop the Error Event -To customize or drop the error event, you need to do a [manual initialization](/platforms/android/configuration/manual-init/#manual-initialization) of the Sentry Android SDK. +To customize or drop the error event, you need to do a [manual initialization](/platforms/android/manual-setup/#configuration-via-sentryoptions) of the Sentry Android SDK. The captured error event can be customized or dropped with a `BeforeSendCallback`: diff --git a/docs/platforms/android/integrations/timber/index.mdx b/docs/platforms/android/integrations/timber/index.mdx index d3ee3137a8511..8e94f0151694d 100644 --- a/docs/platforms/android/integrations/timber/index.mdx +++ b/docs/platforms/android/integrations/timber/index.mdx @@ -62,7 +62,7 @@ configurations.configureEach { ### Install -To add the Timber integration, [manually initialize](/platforms/android/configuration/manual-init/#manual-initialization) the Android SDK, then add the `sentry-android-timber` dependency. Using Gradle: +To add the Timber integration, [manually initialize](/platforms/android/manual-setup/#configuration-via-sentryoptions) the Android SDK, then add the `sentry-android-timber` dependency. Using Gradle: ```groovy implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '4.2.0') }}' diff --git a/docs/platforms/android/manual-setup/index.mdx b/docs/platforms/android/manual-setup/index.mdx index b2612b29ee75e..5c4ddc2ccd3c8 100644 --- a/docs/platforms/android/manual-setup/index.mdx +++ b/docs/platforms/android/manual-setup/index.mdx @@ -26,7 +26,29 @@ plugins { Version `{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}` of the plugin will automatically add the Sentry Android SDK (version `{{@inject packages.version('sentry.java.android', '4.2.0') }}`) to your app. -## Configuration +### Manual Installation + +If you don't want the Sentry Gradle plugin to install the Sentry SDK automatically, you can define the dependency directly in the `build.gradle` file of your app module. + +```groovy {filename:app/build.gradle} +dependencies { + implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '4.2.0') }}' +} +``` + +```kotlin {filename:app/build.gradle.kts} +dependencies { + implementation("io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '4.2.0') }}") +} +``` + + + +If you're using multiple Sentry dependencies, you can add a [bill of materials](/platforms/android/configuration/bill-of-materials) to avoid specifying the version of each dependency. + + + +## Configuration via AndroidManifest.xml Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started: @@ -39,7 +61,7 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp - + @@ -61,13 +83,170 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp + See the Android Session Replay documentation for details: https://docs.sentry.io/platforms/android/session-replay/#screenshot-strategy --> + + + + + + ``` Under the hood, Sentry uses a `ContentProvider` to initialize the SDK based on the values provided above. This way, the SDK can capture important crashes and metrics right from the app start. +## Configuration via SentryOptions + +Initialize the SDK manually when you need to provide additional configuration to the SDK that cannot be specified in the manifest. + +To initialize the SDK manually, disable the auto initialization. You can do so by adding the following line into your manifest: + +```xml {filename:AndroidManifest.xml} + + + +``` + +Or, to completely remove the merging of the `ContentProvider`: + +```xml {filename:AndroidManifest.xml} + + + + + +``` + +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. So, we recommend calling `SentryAndroid.init` in the instance your Application class right after the application is created. If you don't have a custom Application class yet, [checkout 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. + +```kotlin +import io.sentry.ScreenshotStrategyType; +import io.sentry.SentryLevel; +import io.sentry.ProfileLifecycle; +import io.sentry.android.core.SentryAndroid; +import android.app.Application; +import io.sentry.SentryOptions + +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + SentryAndroid.init(this) { options -> + // Required: set your sentry.io project identifier (DSN) + options.dsn = "___PUBLIC_DSN___" + // Add data like request headers, user ip address and device name, see https://docs.sentry.io/platforms/android/data-management/data-collected/ for more info + options.isSendDefaultPii = true + // enable automatic traces for user interactions (clicks, swipes, scrolls) + options.isEnableUserInteractionTracing = true + // enable screenshot for crashes + options.isAttachScreenshot = true + // enable view hierarchy for crashes + options.isAttachViewHierarchy = true + // enable the performance API by setting a sample-rate, adjust in production env + options.tracesSampleRate = 1.0 + // enable UI profiling, adjust in production env. This is evaluated only once per session + options.profileSessionSampleRate = 1.0 + // set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling + options.profileLifecycle = ProfileLifecycle.TRACE + // enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes + options.isStartProfilerOnAppStart = true + // record session replays for 100% of errors and 10% of sessions + options.sessionReplay.sessionSampleRate = 0.1 + options.sessionReplay.onErrorSampleRate = 1.0 + + // 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 + // options.sessionReplay.screenshotStrategy = ScreenshotStrategyType.CANVAS + + // enable logs to be sent to Sentry. Use Sentry.logger() to capture logs or check the available integrations that capture logs automatically: https://docs.sentry.io/platforms/android/logs/#integrations + options.logs.isEnabled = true; + + // enable tombstone support for richer Native crashes context. See more at https://docs.sentry.io/platforms/android/configuration/tombstones/ + options.isTombstoneEnabled = true; + + // Add a callback that will be used before the event is sent to Sentry. + // With this callback, you can modify the event or, when returning null, also discard the event. + options.beforeSend = + SentryOptions.BeforeSendCallback { event, hint -> + if (SentryLevel.DEBUG == event.level) { + null + } else { + event + } + } + } + } +} +``` + +```java +import io.sentry.ScreenshotStrategyType; +import io.sentry.SentryLevel; +import io.sentry.ProfileLifecycle; +import io.sentry.android.core.SentryAndroid; +import android.app.Application; + +public class MyApplication extends Application { + public void onCreate() { + super.onCreate(); + + SentryAndroid.init(this, options -> { + // Required: set your sentry.io project identifier (DSN) + options.setDsn("___PUBLIC_DSN___"); + // Add data like request headers, user ip address and device name, see https://docs.sentry.io/platforms/android/data-management/data-collected/ for more info + options.setSendDefaultPii(true); + // enable automatic traces for user interactions (clicks, swipes, scrolls) + options.setEnableUserInteractionTracing(true); + // enable screenshot for crashes + options.setAttachScreenshot(true); + // enable view hierarchy for crashes + options.setAttachViewHierarchy(true); + // enable the performance API by setting a sample-rate, adjust in production env + options.setTracesSampleRate(1.0); + // enable UI profiling, adjust in production env. This is evaluated only once per session + options.setProfileSessionSampleRate(1.0); + // set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling + options.setProfileLifecycle(ProfileLifecycle.TRACE); + // enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes + options.setStartProfilerOnAppStart(true); + // record session replays for 100% of errors and 10% of sessions + options.getSessionReplay().setSessionSampleRate(0.1); + options.getSessionReplay().setOnErrorSampleRate(1.0); + + // 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 + // options.getSessionReplay().setScreenshotStrategy(ScreenshotStrategyType.CANVAS); + + // enable logs to be sent to Sentry. Use Sentry.logger() to capture logs or check the available integrations that capture logs automatically: https://docs.sentry.io/platforms/android/logs/#integrations + options.getLogs().setEnabled(true); + + // enable tombstone support for richer Native crashes context. See more at https://docs.sentry.io/platforms/android/configuration/tombstones/ + options.setTombstoneEnabled(true); + + // Add a callback that will be used before the event is sent to Sentry. + // With this callback, you can modify the event or, when returning null, also discard the event. + options.setBeforeSend((event, hint) -> { + if (SentryLevel.DEBUG.equals(event.getLevel())) { + return null; + } else { + return event; + } + }); + }); + } +} +``` + Additional options can be found on our dedicated options page. -If you want to customize the SDK init behaviour, you can still use the Manual Initialization method. diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx index 6fc337f7c0df2..2c8438b01e28d 100644 --- a/docs/platforms/android/session-replay/configuration.mdx +++ b/docs/platforms/android/session-replay/configuration.mdx @@ -7,7 +7,7 @@ og_image: /og-images/platforms-android-session-replay-configuration.png ## General Configuration -On Android you configure Session Replay by creating `` entries inside your `AndroidManifest.xml` ([Options configuration](/platforms/android/configuration/options/)), or alternatively in code `SentryAndroid.init(context) { options -> ... }` ([Manual Initialization](/platforms/android/configuration/manual-init/#manual-initialization)). +On Android you configure Session Replay by creating `` entries inside your `AndroidManifest.xml` ([Options configuration](/platforms/android/configuration/options/)), or alternatively in code `SentryAndroid.init(context) { options -> ... }` ([Manual Initialization](/platforms/android/manual-setup/#configuration-via-sentryoptions)). The SDK exposes the following main options to configure Session Replay for your project: | Key | AndroidManifest | Type | Default | Description | diff --git a/docs/platforms/android/troubleshooting/index.mdx b/docs/platforms/android/troubleshooting/index.mdx index 67d658e2be592..8eeb5f69dd406 100644 --- a/docs/platforms/android/troubleshooting/index.mdx +++ b/docs/platforms/android/troubleshooting/index.mdx @@ -10,7 +10,7 @@ sidebar_section: configuration If stack traces don't get deobfuscated properly, even though mapping files are uploaded correctly, or if Android context information is missing from events, a possible reason is that the SDK is initialized with `Sentry.init` instead of `SentryAndroid.init`. -For manual initialization on Android, always use `SentryAndroid.init`. +For manual initialization on Android, always use `SentryAndroid.init`. From SDK version `8.0.0` on, using `Sentry.init` on Android will throw an `IllegalArgumentException`. diff --git a/docs/platforms/dart/guides/flutter/native-init.mdx b/docs/platforms/dart/guides/flutter/native-init.mdx index 1b8648ff93281..113e0de92c627 100644 --- a/docs/platforms/dart/guides/flutter/native-init.mdx +++ b/docs/platforms/dart/guides/flutter/native-init.mdx @@ -18,7 +18,7 @@ This will prevent the Flutter SDK from initializing the native SDKs automaticall Next, initialize the native SDKs as specified in the guides below. -- [Android](/platforms/android/configuration/manual-init/#manual-initialization) +- [Android](/platforms/android/manual-setup/#configuration-via-sentryoptions) - [iOS](/platforms/apple/guides/ios/manual-setup/) - [Browser](/platforms/javascript/#configure) diff --git a/docs/platforms/react-native/manual-setup/native-init.mdx b/docs/platforms/react-native/manual-setup/native-init.mdx index 28f5693fe7b56..2a63e94ebe9ed 100644 --- a/docs/platforms/react-native/manual-setup/native-init.mdx +++ b/docs/platforms/react-native/manual-setup/native-init.mdx @@ -52,4 +52,4 @@ To use auto-init, add the following to your `AndroidManifest.xml`: Then follow [the guide on initializing Android](/platforms/android/#configure). -If you want to manually initialize the Android SDK without using the content provider, you can then [follow the manual initialization guide](/platforms/android/configuration/manual-init/#manual-initialization) without needing to add the tag since `io.sentry.auto-init` is set to `false` by the React Native SDK. +If you want to manually initialize the Android SDK without using the content provider, you can then [follow the manual initialization guide](/platforms/android/manual-setup/#configuration-via-sentryoptions) without needing to add the tag since `io.sentry.auto-init` is set to `false` by the React Native SDK. diff --git a/platform-includes/configuration/config-intro/android.mdx b/platform-includes/configuration/config-intro/android.mdx index e09f0579939d6..438c69dc7a65d 100644 --- a/platform-includes/configuration/config-intro/android.mdx +++ b/platform-includes/configuration/config-intro/android.mdx @@ -5,4 +5,4 @@ Options on Android can be set by setting the values on the `AndroidManifest.xml` ``` -Or, if you are manually instrumenting Sentry, follow the [Manual Initialization](/platforms/android/configuration/manual-init/#manual-initialization) configuration. +Or, if you are manually instrumenting Sentry, follow the [Manual Initialization](/platforms/android/manual-setup/#configuration-via-sentryoptions) configuration. diff --git a/src/middleware.ts b/src/middleware.ts index 6bdd31c0040c4..81244187b789b 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1022,7 +1022,11 @@ const USER_DOCS_REDIRECTS: Redirect[] = [ }, { from: '/platforms/android/manual-configuration/', - to: '/platforms/android/configuration/manual-init/', + to: '/platforms/android/manual-setup/', + }, + { + from: '/platforms/android/configuration/manual-init/', + to: '/platforms/android/manual-setup/', }, { from: '/platforms/android/advanced-usage/',