Skip to content

feat: Connect WebView traces with app traces - #9474

Merged
antonis merged 13 commits into
mainfrom
feat/webview-trace-propagation
Nov 4, 2026
Merged

antonis merged 13 commits into
mainfrom
feat/webview-trace-propagation

Conversation

@antonis

@antonis antonis commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

📜 Description

Builds on #9487, which extracted the outgoing trace lookup from SentryNetworkTracker. #9488 adds the SentryObjC API on top.

Adds SentryWebViewTracing.addTracePropagation(to:options:), which connects the app's trace with web content in a WKWebView.

SentryWebViewTracing.addTracePropagation(
    to: webView,
    options: SentryWebViewTracingOptions(allowedHosts: ["app.example.com"])
)
webView.load(URLRequest(url: URL(string: "https://app.example.com")!))

Before any page script runs, the current trace is written into pages from the allowed hosts as sentry-trace and baggage meta tags, using a WKUserScript at document start. A @sentry/browser running in the page then continues the trace on pageload.

  • Accepts a WKWebView, WKWebViewConfiguration, WKUserContentController, or SwiftUI WebPage.Configuration (iOS 26+). The SentryObjC API follows in feat: Add SentryObjC WebView trace propagation #9488.
  • allowedHosts is a trust boundary, separate from tracePropagationTargets. A page matches an entry's host or its subdomains.
  • Only the main frame receives the trace, and sentry-transaction is removed from baggage.
  • Calling it again replaces Sentry's script with a fresh snapshot of the trace.
  • Each call records a WebViewTracePropagation integration for feature adoption.
  • The script and host normalization match sentry-react-native#6794 and sentry-java#6395. Unlike Android, any scheme is allowed, so pages served through custom scheme handlers (for example Capacitor's capacitor://localhost) work; App Transport Security already blocks plain http by default.

⚠️ Note for reviewing: I understand that this is a big PR since it also includes tests and the sample update I used for verification. I'll be happy to split those in a separate PR if it makes more sense 🙏

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed. (docs: Update Apple WebView guidance for connected traces #9136)
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

Add SentryWebViewTracing.addTracePropagation(to:options:), which
injects the current trace as sentry-trace and baggage meta tags into
pages on allowed hosts before page scripts run, so @sentry/browser
continues the trace on pageload.

It accepts a WKUserContentController, WKWebViewConfiguration,
WKWebView, or SwiftUI WebPage.Configuration (iOS 26+). SentryObjC
exposes it as SentryObjCWebViewTracing. The injected script and host
normalization match sentry-react-native and sentry-java. Using the
API records the WebViewTracePropagation integration for adoption.

Extract the outgoing trace lookup from the network tracker into
SentryOutgoingTrace so both paths share it.
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor
Messages
📖 Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 27957f8

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@antonis antonis added the run-full-ci Allows gated GitHub Action workflows to run for a labelled pull request label Oct 28, 2026
@sentry

sentry Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Size Analysis

1 component analyzed

iOS Builds

Name Configuration Version Download Size Install Size
SDK-Size (iOS)
io.sentry.sample.SDK-Size
Release 9.32.0 (1) 1.2 MB (+403 B) 3.2 MB (0 B)

Configure sentry-cocoa status check rules

@sentry

sentry Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

📲 Install Builds

iOS

🔗 App Name App ID Version Configuration
SDK-Size io.sentry.sample.SDK-Size 9.32.0 (1) Release

⚙️ sentry-cocoa Build Distribution Settings

Run @sentry/browser in the iOS-Swift WebView screen so its pageload
continues the app's trace, and add a SwiftUI WebPage screen on
iOS 26. UI tests check that both pages see the injected trace before
their own scripts run.

Add a test that loads a page in a real WebPage created from a
configuration with Sentry's script.
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

🚨 Detected changes in high risk code 🚨

High-risk code can easily blow up and is hard to test. We had severe bugs in the past. Be extra careful when changing these files, and have an extra careful look at these:

  • Sources/Swift/Networking/SentryNetworkTracker.swift

Move the lookup of the trace propagated to outgoing requests from
SentryNetworkTracker into SentryOutgoingTrace: the span bound to the
scope if it belongs to a tracer, otherwise the scope's propagation
context. Behavior is unchanged.

This lets WebView trace propagation reuse the same lookup.
@antonis antonis mentioned this pull request Oct 29, 2026
4 tasks done
@antonis
antonis changed the base branch from main to ref/outgoing-trace October 29, 2026 10:03
Move SentryObjCWebViewTracing, its tests, and the SentryObjC API
snapshots to a separate pull request stacked on this one, to keep
this one focused on the Swift API.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 973db93. Configure here.

@antonis
antonis marked this pull request as ready for review October 29, 2026 12:33
@antonis
antonis requested review from a team and noahsmartin as code owners October 29, 2026 12:33
@antonis
antonis requested review from itaybre, philprime and runningcode and removed request for a team October 29, 2026 12:33
@antonis
antonis requested review from 0xadam-brown, alwx and buenaflor and removed request for a team October 29, 2026 12:33

@itaybre itaybre left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost LGTM, one small question

Base automatically changed from ref/outgoing-trace to main November 3, 2026 08:23
Resolve the current hub once in addTracePropagation and pass it to
both the adoption marker and the script install, and replace the test
Hub double with real hubs.

Keep SentrySDKWrapper.dsn internal: the sample pages read the DSN from
SentrySDK.startOption instead. Merge the changelog entry into the
existing Features section of Unreleased.
The SwiftPM package tests run on the iOS Simulator without a host app.
There, WebKit's web content process intermittently becomes
unresponsive, so the two WebView page-load tests time out. The Xcode
unit test plans and the iOS-Swift UI tests keep covering real page
loads.
@antonis

antonis commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Thank you for the feedback @itaybre 🙇 I've updated the PR. If there are no blockers I'll proceed with merging.

Note that I had to disable a couple of tests 2e5bbee since they started failing consistently without obvious reason. I've tested moving them to Bitrise in #9525 and they are 🟢 again but I think this is a bigger SDK/CI decision.

@antonis
antonis merged commit ef9077a into main Nov 4, 2026
333 of 337 checks passed
@antonis
antonis deleted the feat/webview-trace-propagation branch November 4, 2026 09:00
antonis added a commit to getsentry/sentry-docs that referenced this pull request Nov 5, 2026
<!-- Keep the urgency section so automation can prioritize this PR. You
may delete other sections you don't need. -->

## DESCRIBE YOUR PR

Updates the Apple WebView page for the new trace connection in the Cocoa
SDK. It replaces the statement that the SDK doesn't interact with web
views with setup for `SentryWebViewTracing.addTracePropagation`, which
writes the app's trace into `WKWebView` pages as `sentry-trace` and
`baggage` meta tags before page scripts run, so `@sentry/browser`
continues it on pageload.

- Swift and SentryObjC examples, plus a SwiftUI `WebPage` section (iOS,
macOS, visionOS 26+)
- `allowedHosts` matching and the trust warning, aligned with the [React
Native WebView
page](https://docs.sentry.io/platforms/react-native/configuration/webview/)
- The snapshot behavior, supported platforms, and limitations

Resolves getsentry/sentry-cocoa#9136

> ⚠️ SDK changes: getsentry/sentry-cocoa#9474 (Swift API) and
getsentry/sentry-cocoa#9488 (SentryObjC API). The version alert says
`9.33.0`; it will be updated if the release differs. Keep this as a
draft until those PRs ship.

## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the
due date. You can update this information later by editing the PR
description.

- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] No deadline: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
supplied a deadline.

Thanks in advance for your help!

## PRE-MERGE CHECKLIST

_Make sure you've checked the following before merging your changes:_

- [ ] 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)

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved run-full-ci Allows gated GitHub Action workflows to run for a labelled pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Track WebView trace-connection feature adoption Add support for WebViews

2 participants