From fb03f93d38795d0b00b58cd2f57eaeae4b0abedc Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Thu, 5 Nov 2026 12:18:35 +0100 Subject: [PATCH 1/8] docs(android): Document connecting WebView traces Replace the Android WebView guidance, which said the SDK doesn't interact with web views, with setup for SentryWebViewTracing. addTracePropagation, matching the Apple and React Native pages. Co-Authored-By: Claude Opus 5.5 --- .../android/configuration/webview.mdx | 129 +++++++++++++++++- 1 file changed, 125 insertions(+), 4 deletions(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index f8765dd113ea5..57a7b90bf7087 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -1,22 +1,143 @@ --- title: WebView -description: "Learn how to set up the Sentry Android and Browser SDKs with WebView." +description: "Learn how to connect traces and monitor errors and performance across the Sentry Android and Browser SDKs with WebView." --- -To monitor errors and performance in web views of Android applications, you need to set up Sentry SDKs in both the mobile application and the web projects running in the web views. +To monitor errors and performance in web views of Android applications, you set up Sentry SDKs in both the mobile application and the web projects running in the web views. You can also connect their traces, so a single distributed trace spans your app and the web content it embeds. ## Application Monitoring -The Sentry Android SDK doesn't interact with the mobile application's web views. To monitor errors and performance in the Android part of the application follow the [Sentry Android SDK setup instructions](/platforms/android/). +To monitor errors and performance in the native part of the application, follow the [Sentry Android SDK setup instructions](/platforms/android/). The Android SDK doesn't capture errors that happen inside a web view — those are captured by the JavaScript SDK running in the web project (see [WebView Monitoring](#webview-monitoring)). ## WebView Monitoring -To monitor errors and performance in web views choose the appropriate Sentry JavaScript SDK depending on the framework used in the web project. +To monitor errors and performance in web views, choose the appropriate Sentry JavaScript SDK depending on the framework used in the web project. - [Sentry React SDK](/platforms/javascript/guides/react/) (if the web project uses React) - [Sentry Angular SDK](/platforms/javascript/guides/angular/) (if the web project uses Angular) - [Other Sentry JavaScript SDKs](/platforms/javascript/) +## Connect Traces + + + +`SentryWebViewTracing` is available from Android SDK version `8.64.0`. + + + +Use `SentryWebViewTracing.addTracePropagation` to inject your app's trace into an `android.webkit.WebView`. The Browser SDK running in the web page picks it up on pageload and continues the same trace, so the web page's pageload transaction and errors share the trace of your app. The result is a single connected trace across the native and web parts of the user journey. + +Trace propagation uses the [AndroidX WebKit](https://developer.android.com/jetpack/androidx/releases/webkit) library, which the Android SDK doesn't add for you. Add it to your app: + +```kotlin {filename:app/build.gradle.kts} +dependencies { + implementation("androidx.webkit:webkit:1.14.0") +} +``` + +Then call `addTracePropagation` before the web view loads the page: + +```kotlin {tabTitle:Kotlin} +import io.sentry.android.core.SentryWebViewTracing + +SentryWebViewTracing.addTracePropagation(webView, "example.com") +webView.loadUrl("https://example.com") +``` + +```java {tabTitle:Java} +import io.sentry.android.core.SentryWebViewTracing; + +SentryWebViewTracing.addTracePropagation(webView, "example.com"); +webView.loadUrl("https://example.com"); +``` + +You can pass several hosts, or a `List`. Trace propagation applies to pages that start loading after the call. Call it from the main thread. The method returns `false` if nothing was added, for example when the `androidx.webkit` dependency is missing, the device's System WebView doesn't support it, no host is valid, the SDK isn't initialized, or it's called from another thread. + +For the connection to take effect: + +- The web page must run a Sentry [Browser SDK](/platforms/javascript/) with tracing enabled (the `browserTracingIntegration`). It continues the trace from the injected `sentry-trace` and `baggage` `` tags automatically, the same way it continues a trace started by a server (see [Distributed Tracing](/platforms/javascript/tracing/distributed-tracing/)) — no additional configuration is needed on the web page. The SDK writes the tags with a document-start script, before any page script runs, so the Browser SDK can be initialized anywhere in the page. +- The hosts you pass declare the hosts you trust to load in this web view. A page is matched when it's served over HTTPS and its hostname equals an entry or is a subdomain of it (for example, `"example.com"` matches both `example.com` and `app.example.com`). Matching is case-insensitive. Entries are normalized, so a scheme, path, trailing dot, or leading `*.` is ignored, and internationalized hostnames are converted to their ASCII form. A port other than `443` limits the entry to pages served on that port (for example, `"example.com:8443"`). The trace context is only written on matching pages, and only in the main frame, not in iframes. + + + +Only list hosts whose content you trust. The trace context is injected into every matching page, so an allow-listed page that runs untrusted JavaScript can read it back and feed misleading or polluted data into the connected trace. This risk is bounded by the hosts you list — don't allow-list pages that render untrusted or third-party content. + +The hosts are enforced by the web view and also checked inside the web page as defense-in-depth for honest cross-host navigation, but they're **not a strict security boundary**, since a hostile page sharing the web view could bypass an in-page check. + +The injected trace context carries no secrets or PII by default: the root span name (`sentry-transaction`), which can contain parameterized URLs, is stripped from `baggage` before it is injected. Still, don't put sensitive data in `baggage` for web views that may load untrusted pages. + + + + + +The injected trace is a snapshot taken when you call `addTracePropagation`, and every later page load in that web view reuses it. To connect a later page load to a newer trace, call `addTracePropagation` again before the navigation. It replaces the script Sentry added earlier and keeps your own scripts. + + + +### Pages Bundled With Your App + +Pages loaded with `loadData`, with `loadDataWithBaseURL` and a base URL that isn't HTTPS, or from `file://` URLs don't receive the trace. To show pages bundled with your app, serve them over HTTPS with [`WebViewAssetLoader`](https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader) and allow its domain: + +```kotlin {tabTitle:Kotlin} +import android.webkit.WebResourceRequest +import android.webkit.WebResourceResponse +import android.webkit.WebView +import android.webkit.WebViewClient +import androidx.webkit.WebViewAssetLoader +import io.sentry.android.core.SentryWebViewTracing + +val assetLoader = + WebViewAssetLoader.Builder() + .addPathHandler("/assets/", WebViewAssetLoader.AssetsPathHandler(context)) + .build() +webView.webViewClient = + object : WebViewClient() { + override fun shouldInterceptRequest( + view: WebView, + request: WebResourceRequest, + ): WebResourceResponse? = assetLoader.shouldInterceptRequest(request.url) + } + +SentryWebViewTracing.addTracePropagation(webView, WebViewAssetLoader.DEFAULT_DOMAIN) +webView.loadUrl("https://${WebViewAssetLoader.DEFAULT_DOMAIN}/assets/index.html") +``` + +```java {tabTitle:Java} +import android.webkit.WebResourceRequest; +import android.webkit.WebResourceResponse; +import android.webkit.WebView; +import android.webkit.WebViewClient; +import androidx.webkit.WebViewAssetLoader; +import io.sentry.android.core.SentryWebViewTracing; + +WebViewAssetLoader assetLoader = + new WebViewAssetLoader.Builder() + .addPathHandler("/assets/", new WebViewAssetLoader.AssetsPathHandler(context)) + .build(); +webView.setWebViewClient( + new WebViewClient() { + @Override + public WebResourceResponse shouldInterceptRequest( + WebView view, WebResourceRequest request) { + return assetLoader.shouldInterceptRequest(request.getUrl()); + } + }); + +SentryWebViewTracing.addTracePropagation(webView, WebViewAssetLoader.DEFAULT_DOMAIN); +webView.loadUrl("https://" + WebViewAssetLoader.DEFAULT_DOMAIN + "/assets/index.html"); +``` + +### Limitations + +- Trace propagation requires an Android System WebView that supports document-start scripts (`WebViewFeature.DOCUMENT_START_SCRIPT`). On older WebViews, `addTracePropagation` returns `false` and the web page starts its own trace. +- Only `android.webkit.WebView` is supported, including a `WebView` shown with `AndroidView` in Jetpack Compose. Custom Tabs and Trusted Web Activities run in the browser app, so scripts can't be injected into them. +- Only HTTPS pages receive the trace. +- When no span is active, the injected trace doesn't carry a sampling decision, so the Browser SDK makes its own sampling decision for the web page. + +The trace is connected on the web page's initial load. Client-side navigations within a single-page app in the web view start their own traces, as they do in a regular browser. + +The app and the web project can report to different Sentry projects — as long as they're in the same organization, the trace view stitches the transactions together by trace ID. + ## Notes - The JavaScript SDK should be initialized when the web view is created and will be closed when the web view is closed. To monitor all web views in the application, initialize the JavaScript SDK every time a web view is created. From e48055298e174cfd8ebd62165484627290261751 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Fri, 13 Nov 2026 15:27:21 +0100 Subject: [PATCH 2/8] docs(android): Document the WebView allowed hosts option (#20687) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Documents setting the WebView allowed hosts once in the Android SDK options, added in getsentry/sentry-java#6516. Stacked on #20550. Adds a section to the Android WebView page covering `options.webViewTracing.allowedHosts`, the `io.sentry.webview-tracing.allowed-hosts` manifest entry, and `SentryWebViewTracing.addTracePropagation(webView)`. This is a draft until the SDK change is merged. ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 --- .../android/configuration/webview.mdx | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index 57a7b90bf7087..f3c9a4e26db00 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -74,6 +74,49 @@ The injected trace is a snapshot taken when you call `addTracePropagation`, and +### Set the Allowed Hosts in the SDK Options + +To avoid listing the hosts on every call, set them once in the SDK options and call `addTracePropagation` without hosts: + +```kotlin {tabTitle:Kotlin} +import io.sentry.android.core.SentryAndroid +import io.sentry.android.core.SentryWebViewTracing + +SentryAndroid.init(context) { options -> + options.webViewTracing.allowedHosts = listOf("example.com") +} + +SentryWebViewTracing.addTracePropagation(webView) +webView.loadUrl("https://example.com") +``` + +```java {tabTitle:Java} +import io.sentry.android.core.SentryAndroid; +import io.sentry.android.core.SentryWebViewTracing; +import java.util.Collections; + +SentryAndroid.init(context, options -> { + options.getWebViewTracing().setAllowedHosts(Collections.singletonList("example.com")); +}); + +SentryWebViewTracing.addTracePropagation(webView); +webView.loadUrl("https://example.com"); +``` + +You can also set them in your manifest, as a comma-separated list: + +```xml {filename:AndroidManifest.xml} + + + +``` + +The list is empty by default, so without hosts `addTracePropagation(webView)` logs a warning and returns `false`. Hosts you pass to `addTracePropagation` are used instead of the ones in the options. The same matching rules and the warning above apply to both. + +`allowedHosts` is separate from [`tracePropagationTargets`](/platforms/android/configuration/options/#tracePropagationTargets), which controls outgoing HTTP requests. Setting one doesn't affect the other. + ### Pages Bundled With Your App Pages loaded with `loadData`, with `loadDataWithBaseURL` and a base URL that isn't HTTPS, or from `file://` URLs don't receive the trace. To show pages bundled with your app, serve them over HTTPS with [`WebViewAssetLoader`](https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader) and allow its domain: From 43c1d72f1e99d547a0c3a0068877455e3d980a8b Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:41 +0100 Subject: [PATCH 3/8] docs(android): Move the web view errors note to the WebView page's notes Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index f3c9a4e26db00..6baac43c6a106 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -7,7 +7,7 @@ To monitor errors and performance in web views of Android applications, you set ## Application Monitoring -To monitor errors and performance in the native part of the application, follow the [Sentry Android SDK setup instructions](/platforms/android/). The Android SDK doesn't capture errors that happen inside a web view — those are captured by the JavaScript SDK running in the web project (see [WebView Monitoring](#webview-monitoring)). +To monitor errors and performance in the native part of the application, follow the [Sentry Android SDK setup instructions](/platforms/android/). ## WebView Monitoring @@ -183,6 +183,8 @@ The app and the web project can report to different Sentry projects — as long ## Notes +- The Android SDK doesn't capture errors that happen inside a web view. Those are captured by the JavaScript SDK running in the web project (see [WebView Monitoring](#webview-monitoring)). + - The JavaScript SDK should be initialized when the web view is created and will be closed when the web view is closed. To monitor all web views in the application, initialize the JavaScript SDK every time a web view is created. - If the web project is accessed remotely and not unique to the mobile application (for example the project also works as a standalone web application), we recommend using separate Sentry projects for the mobile application and the web project. From 7c80e76d417cff2bf48414dce8515e25711c9911 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:42 +0100 Subject: [PATCH 4/8] docs(android): Recommend the latest SDK version for WebView tracing Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index 6baac43c6a106..3dd08d455e141 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -21,7 +21,7 @@ To monitor errors and performance in web views, choose the appropriate Sentry Ja -`SentryWebViewTracing` is available from Android SDK version `8.64.0`. +`SentryWebViewTracing` is available from Android SDK version `8.64.0`, but we always recommend using the latest version for the latest bug fixes and performance improvements. From 61115573fff673d9ae36613da073a6865c350eb5 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:42 +0100 Subject: [PATCH 5/8] docs(android): Clarify passing several WebView hosts Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index 3dd08d455e141..f981ee52f78c2 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -51,7 +51,7 @@ SentryWebViewTracing.addTracePropagation(webView, "example.com"); webView.loadUrl("https://example.com"); ``` -You can pass several hosts, or a `List`. Trace propagation applies to pages that start loading after the call. Call it from the main thread. The method returns `false` if nothing was added, for example when the `androidx.webkit` dependency is missing, the device's System WebView doesn't support it, no host is valid, the SDK isn't initialized, or it's called from another thread. +To allow several hosts, pass them as separate arguments, for example `addTracePropagation(webView, "example.com", "example.org")`, or as a `List`. Trace propagation applies to pages that start loading after the call. Call it from the main thread. The method returns `false` if nothing was added, for example when the `androidx.webkit` dependency is missing, the device's System WebView doesn't support it, no host is valid, the SDK isn't initialized, or it's called from a thread other than the main thread. For the connection to take effect: From 79e790bd7d8e49e5d74706fed81a15ce0d2d4847 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:42 +0100 Subject: [PATCH 6/8] docs(android): Split the WebView host matching rules into bullets Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index f981ee52f78c2..be0ee45c2e32e 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -56,7 +56,11 @@ To allow several hosts, pass them as separate arguments, for example `addTracePr For the connection to take effect: - The web page must run a Sentry [Browser SDK](/platforms/javascript/) with tracing enabled (the `browserTracingIntegration`). It continues the trace from the injected `sentry-trace` and `baggage` `` tags automatically, the same way it continues a trace started by a server (see [Distributed Tracing](/platforms/javascript/tracing/distributed-tracing/)) — no additional configuration is needed on the web page. The SDK writes the tags with a document-start script, before any page script runs, so the Browser SDK can be initialized anywhere in the page. -- The hosts you pass declare the hosts you trust to load in this web view. A page is matched when it's served over HTTPS and its hostname equals an entry or is a subdomain of it (for example, `"example.com"` matches both `example.com` and `app.example.com`). Matching is case-insensitive. Entries are normalized, so a scheme, path, trailing dot, or leading `*.` is ignored, and internationalized hostnames are converted to their ASCII form. A port other than `443` limits the entry to pages served on that port (for example, `"example.com:8443"`). The trace context is only written on matching pages, and only in the main frame, not in iframes. +- The hosts you pass declare the hosts you trust to load in this web view: + - A page is matched when it's served over HTTPS and its hostname equals an entry or is a subdomain of it. For example, `"example.com"` matches both `example.com` and `app.example.com`. + - Matching is case-insensitive. A scheme, path, trailing dot, or leading `*.` in an entry is ignored, and internationalized hostnames are converted to their ASCII form. + - A port other than `443` limits the entry to pages served on that port, for example `"example.com:8443"`. + - The trace context is only written on matching pages, and only in the main frame, not in iframes. From b02a8e8690dd43680e586d4d47bcaef2266fc2e9 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:42 +0100 Subject: [PATCH 7/8] docs(android): Keep only the trust warning in the WebView alert Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index be0ee45c2e32e..761b66ac75998 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -66,12 +66,12 @@ For the connection to take effect: Only list hosts whose content you trust. The trace context is injected into every matching page, so an allow-listed page that runs untrusted JavaScript can read it back and feed misleading or polluted data into the connected trace. This risk is bounded by the hosts you list — don't allow-list pages that render untrusted or third-party content. + + The hosts are enforced by the web view and also checked inside the web page as defense-in-depth for honest cross-host navigation, but they're **not a strict security boundary**, since a hostile page sharing the web view could bypass an in-page check. The injected trace context carries no secrets or PII by default: the root span name (`sentry-transaction`), which can contain parameterized URLs, is stripped from `baggage` before it is injected. Still, don't put sensitive data in `baggage` for web views that may load untrusted pages. - - The injected trace is a snapshot taken when you call `addTracePropagation`, and every later page load in that web view reuses it. To connect a later page load to a newer trace, call `addTracePropagation` again before the navigation. It replaces the script Sentry added earlier and keeps your own scripts. From 2e4d84d972b1a44fecb1a193ddae16bda6fa0ea8 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 17 Nov 2026 14:54:42 +0100 Subject: [PATCH 8/8] docs(android): Show the WebView trace snapshot note as plain text Co-Authored-By: Claude Opus 5.5 --- docs/platforms/android/configuration/webview.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/platforms/android/configuration/webview.mdx b/docs/platforms/android/configuration/webview.mdx index 761b66ac75998..814d9386503b4 100644 --- a/docs/platforms/android/configuration/webview.mdx +++ b/docs/platforms/android/configuration/webview.mdx @@ -72,12 +72,8 @@ The hosts are enforced by the web view and also checked inside the web page as d The injected trace context carries no secrets or PII by default: the root span name (`sentry-transaction`), which can contain parameterized URLs, is stripped from `baggage` before it is injected. Still, don't put sensitive data in `baggage` for web views that may load untrusted pages. - - The injected trace is a snapshot taken when you call `addTracePropagation`, and every later page load in that web view reuses it. To connect a later page load to a newer trace, call `addTracePropagation` again before the navigation. It replaces the script Sentry added earlier and keeps your own scripts. - - ### Set the Allowed Hosts in the SDK Options To avoid listing the hosts on every call, set them once in the SDK options and call `addTracePropagation` without hosts: