Repository navigation
docs(android): Document connecting WebView traces #20550
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
fb03f93
docs(android): Document connecting WebView traces
antonis 4e0bbc2
Merge branch 'master' into docs/android-webview-trace-propagation
antonis 62dfc3d
Merge branch 'master' into docs/android-webview-trace-propagation
antonis e480552
docs(android): Document the WebView allowed hosts option (#20687)
antonis 936715e
Merge branch 'master' into docs/android-webview-trace-propagation
antonis c42d858
Merge branch 'master' into docs/android-webview-trace-propagation
antonis 43c1d72
docs(android): Move the web view errors note to the WebView page's notes
antonis 7c80e76
docs(android): Recommend the latest SDK version for WebView tracing
antonis 6111557
docs(android): Clarify passing several WebView hosts
antonis 79e790b
docs(android): Split the WebView host matching rules into bullets
antonis b02a8e8
docs(android): Keep only the trust warning in the WebView alert
antonis 2e4d84d
docs(android): Show the WebView trace snapshot note as plain text
antonis 5a83da6
Merge remote-tracking branch 'origin/master' into docs/android-webvie…
antonis File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,24 +1,190 @@ | ||
| --- | ||
| 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/). | ||
|
|
||
| ## 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 | ||
|
|
||
| <Alert> | ||
|
|
||
| `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. | ||
|
|
||
| </Alert> | ||
|
|
||
| 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"); | ||
| ``` | ||
|
|
||
| To allow several hosts, pass them as separate arguments, for example `addTracePropagation(webView, "example.com", "example.org")`, or as a `List<String>`. 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: | ||
|
|
||
| - 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` `<meta>` 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. 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. | ||
|
|
||
| <Alert level="warning"> | ||
|
|
||
| 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. | ||
|
antonis marked this conversation as resolved.
Resolved
|
||
|
|
||
| </Alert> | ||
|
|
||
| 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. | ||
|
antonis marked this conversation as resolved.
Resolved
|
||
|
|
||
| ### 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} | ||
| <application> | ||
| <meta-data | ||
| android:name="io.sentry.webview-tracing.allowed-hosts" | ||
| android:value="example.com,example.org" /> | ||
| </application> | ||
| ``` | ||
|
|
||
| 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: | ||
|
|
||
| ```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 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. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why don't we add it? what would be the downside there?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've kept it optional (compileOnly), like androidx.activity for the feedback form. My understanding is that bundling it would add it to every app. Happy to iterate on this if it makes sense.