Skip to content

Automatic WebView trace instrumentation #6961

Open

Description

@antonis

Follow-up to the WebView trace-connection feature (#6794), which connects React Native ↔ WebView traces via the opt-in sentryWebViewProps helper.

Explore automatic instrumentation so embedded WebViews are connected to the app's trace without wiring up each <WebView> manually.

Approach and details to be defined later.

References: #6794, getsentry/sentry-cocoa#8897, getsentry/sentry-java#6024.

Activity

  1. linear-code commented on Oct 28, 2026

    @linear-code
  2. self-assigned this
    on Oct 28, 2026
  3. antonis commented on Nov 4, 2026

    @antonis
    ContributorAuthor

    Plan: Automatic WebView trace instrumentation

    Background

    v1 (#6794) connects RN ↔ WebView traces via the opt-in sentryWebViewProps({ allowedHosts }) helper, spread onto each <WebView>. This issue is to make that automatic. Core constraint: the RN SDK has no dependency on react-native-webview and can't hook <WebView> globally at runtime (react-native-webview's WebView is a forwardRef functional component — no defaultProps seam; runtime export-patching doesn't reach already-bound imports).

    Two approaches

    A — native auto-instrumentation (recommended; native-first). iOS swizzles WKWebView; Android instruments android.webkit.WebView via the Sentry Android Gradle Plugin (SAGP) bytecode transform. Both inject the document-start script by calling the existing runtime helper (SentryWebViewTracing.addTracePropagation, #6395 — so the manual API is the primitive the auto layer reuses). Because react-native-webview is a thin wrapper over a real WKWebView / android.webkit.WebView, this catches RN's WebViews with no RN JS work — library-agnostic.

    • Correct trace only after the hybrid PropagationContext sync (RN-665 / COCOA-66); before that it injects the native trace, which may differ from the RN navigation trace.
    • The SAGP is already in the RN Android build chain (the SDK applies io.sentry.android.gradle with AppStart/Database/FileIO/Logcat instrumentations), so a new WebViewInstrumentation reaches RN apps that apply SAGP with no new plumbing. Design lives partly in sentry-android-gradle-plugin (the ASM transform) on top of sentry-java.

    B — JS Babel auto-wrap (interim alternative). A Babel plugin rewrites import { WebView } from 'react-native-webview' to wrap it with a runtime wrapWebView() that injects sentryWebViewProps. Precedent: the SDK already ships sentryExpoRouterAutoWrapBabelPlugin + the Metro/Babel toolchain. Uses the correct JS trace with no cross-layer dependency, but only covers react-native-webview in user code (skips node_modules and other WebView libs) and isn't zero-config (needs the Sentry Metro config + a global allowedHosts).

    Coverage comparison

    A (native) B (JS Babel)
    Reaches any real WKWebView/android.webkit.WebView (lib-agnostic) react-native-webview in user code only
    Trace correct after RN-665 correct now
    Hard blocker RN-665 + native auto layer none
    Zero-config ~yes (Android needs SAGP applied) no
    Not covered SFSafariViewController/Custom Tabs; first-navigation timing TBD same, plus non-RNW WebViews

    Neither covers SFSafariViewController / Custom Tabs (web content there isn't injectable).

    Recommendation: native-first → A

    Fix the native side first — build native WebView auto-instrumentation (iOS swizzle; Android SAGP transform) and the RN-665 trace sync. This issue then becomes a thin consume-and-configure layer: bundle the newer native SDKs, enable the instrumentation, expose a global allowedHosts config, and verify on RN. Less RN-specific code, broader coverage, correct trace, and shared with iOS/Android/Flutter. Use B only as an interim if RN auto-instrumentation is needed before native-first lands.

    Keep the manual API

    sentryWebViewProps (and the native helpers) stay — complementary, not redundant: the primitive the auto layer calls, precise per-WebView control, the path for apps without SAGP, and the interim correct-trace path for RN.

    Conflicts (auto + manual)

    • Native auto + native manual: no conflict — both route through the same addTracePropagation, which dedups on the WebView's view-tag ScriptHandler (second call replaces the first).
    • RN manual + native auto: no double tags (both injection scripts carry if(document.querySelector('meta[name="sentry-trace"]'))return;), but a precedence nuance — whichever injects first wins; pre-RN-665 the native script can override the RN JS trace. Moot after RN-665.
    • Mitigation: auto should skip WebViews already carrying a Sentry script/handler, plus a config to exclude or disable it; document "don't double-instrument the same WebView."

    Security

    The allowedHosts trust boundary (SEC-1935) is more important under auto: A instruments every WebView, so without a host allow-list it would leak trace context into third-party / auth WebViews. Auto needs a global allowedHosts; no hosts ⇒ no-op.

    Dependencies / sequencing

    1. RN-665 / COCOA-66 — hybrid PropagationContext sync (blocker for correct trace).
    2. Native WebView auto-instrumentation — new issues: iOS (COCOA, swizzle), Android (JAVA + sentry-android-gradle-plugin, SAGP transform).
    3. This issue — consume + configure + verify on RN; keep the manual API; add the precedence / opt-out rule.

    Out of scope

    SFSafariViewController / Custom Tabs; SPA / in-WebView re-navigation re-connection (already deferred).

    References: #6794, getsentry/sentry-cocoa#8897, getsentry/sentry-java#6024.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions