Android WebView Tracking

A WebView runs an independent JavaScript context, so the Browser Agent inside the page and the Android SDK around it each open their own RUM session. A journey that crosses into embedded web content is recorded as two unrelated sessions with no shared identifier.

WebView tracking installs a JavaScript bridge between the two. Events emitted by the page are re-attributed to the native session, producing a single timeline that spans the native screens, the web content, and the return path.

Before you start

The integration has three requirements:

• The Atatus Android SDK initialized with RUM enabled. See Android Monitoring Setup.
• The Atatus Browser Agent loaded on the pages rendered in the WebView. Without it the page emits no events to correlate.
• JavaScript enabled on the WebView instance, since the bridge is implemented as a JavaScript interface.

Setup

1. Add the WebView dependency

Declare the WebView tracking library in your application module's build.gradle.kts:

dependencies {
    implementation("com.atatus:atatus-sdk-android-webview:1.0.1")
}

2. Enable JavaScript

The bridge is injected as a JavaScript interface and is inert without it:

webView.settings.javaScriptEnabled = true

3. Enable tracking on the WebView

Call WebViewTracking.enable before loading a URL, passing the hosts whose events should be correlated:

import com.atatus.android.webview.WebViewTracking

val allowedHosts = listOf("shop.example.com")

WebViewTracking.enable(webView, allowedHosts)
webView.loadUrl("https://shop.example.com/cart")

The bridge is injected only for documents served from a host in allowedHosts. Pages outside that list render normally and emit no correlated events.

4. Verify the correlation

Open the WebView in your application, then locate the session in your Atatus dashboard. A correlated session interleaves native views and web page views on one timeline. Two separate sessions indicate the bridge did not attach, which has three common causes:

• The Browser Agent is not loaded on the page, so no web events are produced.
• The document's host does not match an entry in allowedHosts exactly, including the subdomain.
• JavaScript is disabled on that specific WebView instance.

Match multiple hosts

Host matching is exact and does not extend to subdomains. Enumerate every origin the WebView loads:

val allowedHosts = listOf(
    "shop.example.com",
    "checkout.example.com",
    "help.example.com"
)

Billing

Correlated web events are attributed to the existing native session rather than opening a second one, so WebView tracking does not increase your session count. Your browser RUM application continues to record its own sessions for users reaching the same pages through a desktop or mobile browser.

Next steps

• Capture exceptions raised by web content with Error Tracking.
• Apply context across both native and web events using global attributes.