Skip to content

ref(apple): add notes on SwiftUI limitations #18352

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.

Sign up for GitHub

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

Open
philprime wants to merge 1 commit into
base: master
Choose a base branch
from
+21 −2
Open

ref(apple): add notes on SwiftUI limitations #18352

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,15 @@ App hang events will not have view hierarchy because the main thread is blocked

<Alert>

Deobfuscation for view hierarchies is fully supported for native SDKs, and React Native, but is currently not supported for Flutter. View hierarchies are not supported for SwiftUI.
Deobfuscation for view hierarchies is fully supported for native SDKs and React Native, but is currently not supported for Flutter.

</Alert>

<Alert>

View hierarchy support for SwiftUI is highly limited, due to the SwiftUI rendering engine not backing every view with a UIKit view anymore.

For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`. This is an operating system limitation, not a limitation of the Sentry SDK. As a result, the captured view hierarchy may not fully represent the SwiftUI view tree.
Comment on lines +29 to +31

@sentry sentry Bot Jun 10, 2026

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.

Bug: The documentation change to "highly limited" support for SwiftUI view hierarchies is misleading if the feature is completely unsupported, setting incorrect user expectations.
Severity: LOW

Suggested Fix

Revert the documentation to state that view hierarchies are "not supported for SwiftUI" to accurately reflect the feature's capability. If there is some partial support, the documentation should be more specific about what is and isn't captured, rather than using ambiguous terms like "highly limited".

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/apple/common/enriching-events/viewhierarchy/index.mdx#L29-L31

Potential issue: The documentation in `index.mdx` is being updated from stating that
view hierarchies are "not supported for SwiftUI" to being "highly limited". This new
wording, particularly the phrase "the captured view hierarchy may not fully represent
the SwiftUI view tree," implies that some view hierarchy data is captured for SwiftUI
applications. However, evidence suggests the feature is completely unsupported for
SwiftUI. This discrepancy can mislead users into expecting partial functionality from
the `attachViewHierarchy` option, leading to confusion when no view hierarchy data is
actually captured.

Did we get this right? 👍 / 👎 to inform future reviews.


</Alert>

Expand Down
8 changes: 8 additions & 0 deletions docs/platforms/apple/common/session-replay/customredact.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,14 @@ label.sentryReplayUnmask()

## SwiftUI

<Alert level="info">

Session Replay masking for SwiftUI is best-effort. The SDK relies on view hierarchy information provided by the operating system, which is limited for SwiftUI. The SwiftUI rendering engine does not back every view with a UIKit view anymore. For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`.

This is an operating system limitation, not a limitation of the Sentry SDK. As a result, some views may not be automatically maskable.

</Alert>

Because of the way SwiftUI is transformed into UIKit, it will often be over-masked. A modifier like `background` uses the same element as an `Image`.
In order to control the SwiftUI masking process, you need to use the `sentryReplayUnmask` and/or `sentryReplayMask` modifiers.

Expand Down
5 changes: 4 additions & 1 deletion docs/platforms/apple/common/session-replay/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ This issue has been resolved in Sentry Cocoa <strong>9.11.0</strong>. Session Re

<Expandable title="Does Session Replay work with UIKit, SwiftUI or AppKit?" permalink>

Session Replay works with both UIKit and SwiftUI.
Session Replay works with both UIKit and SwiftUI. However, SwiftUI support has inherent limitations with masking because the SwiftUI rendering engine does not back every view with a UIKit view.

For example, `Text` views may be rendered directly into a graphics render surface rather than creating a corresponding `UILabel`. This is an operating system limitation, not a limitation of the Sentry SDK. As a result, masking for SwiftUI views is best-effort and some views may not be automatically maskable. See <PlatformLink to="/session-replay/customredact/#swiftui">SwiftUI masking</PlatformLink> for details.

</Expandable>

Expand Down Expand Up @@ -78,6 +80,7 @@ Session Replay cannot capture photo picker interfaces (`PHPickerViewController`
On physical devices, photo pickers and camera views will not appear in session replays. On simulators, they may appear because simulators don't use the same remote rendering approach, but this behavior should not be relied upon.

This limitation exists at the iOS system level and cannot be worked around by configuring `unmaskedViewClasses` or other Session Replay settings.

</Expandable>

<Expandable title="Session Replay is not recording with custom window setup" permalink>
Expand Down
Loading