feat(apple): Update session replay docs with AVFoundation limitation

[philprime]

DESCRIBE YOUR PR

This PR adds a "Known Limitations" section to the iOS Session Replay troubleshooting page. It clarifies that AVFoundation views and layers, such as AVPlayerLayer and AVCaptureVideoPreviewLayer (used for camera previews and video content), cannot be captured by Session Replay. This limitation applies even when using the unmaskedViewClasses configuration.

This update addresses user confusion (as seen in the provided Slack context) where users attempt to unmask AVFoundation-backed views and expect them to appear in replays.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: 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 added an urgent due date to it.
  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

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

---

Slack Thread

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Ready	Preview	Comment	Aug 26, 2025 2:10pm
sentry-docs	Ready	Preview	Comment	Aug 26, 2025 2:10pm

[codecov]

Bundle Report

Changes will decrease total bundle size by 1.15MB (-5.06%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-client-array-push	9.9MB	-6 bytes (-0.0%) ⬇️
sentry-docs-server-cjs	11.33MB	-1.15MB (-9.21%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
static/chunks/pages/_app-*.js	-3 bytes	882.71kB	-0.0%
static/chunks/8321-*.js	-3 bytes	425.87kB	-0.0%
static/Ne_NimT9ogyGsT_L2V5hc/_buildManifest.js (New)	684 bytes	684 bytes	100.0% 🚀
static/Ne_NimT9ogyGsT_L2V5hc/_ssgManifest.js (New)	77 bytes	77 bytes	100.0% 🚀
static/duPpACoAnq_u-*.js (Deleted)	-684 bytes	0 bytes	-100.0% 🗑️
static/duPpACoAnq_u-*.js (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
1729.js	-33.51kB	1.74MB	-1.89%
../instrumentation.js	-33.8kB	1.07MB	-3.07%
9523.js	-33.51kB	1.04MB	-3.11%
../app/[[...path]]/page.js.nft.json	-349.32kB	415.75kB	-45.66%
../app/platform-redirect/page.js.nft.json	-349.32kB	415.66kB	-45.66%
../app/sitemap.xml/route.js.nft.json	-349.32kB	413.13kB	-45.82%
7153.js (New)	29.25kB	29.25kB	100.0% 🚀
../app/api/ip-ranges/route.js	-300 bytes	5.79kB	-4.92%
../app/robots.txt/route.js	-300 bytes	5.02kB	-5.64%
2311.js (Deleted)	-29.86kB	0 bytes	-100.0% 🗑️

App Routes Affected:

App Route	Size Change	Total Size	Change (%)
/	-600 bytes	2.62MB	-0.02%

[jas-kas]

Content-wise the changes look good 👌

I find this Troubleshooting page hard to scan, especially with the "Known Limitations" heading mixed in there.

Can we follow the pattern seen on the JavaScript Troubleshooting page for Replay? https://sentry-docs-git-cursor-update-session-replay-docs-with-a-c0ad0e.sentry.dev/platforms/javascript/session-replay/troubleshooting/

[philprime]

I agree the JS troubleshooting page makes more sense with a larger list of issues.
We can adopt this for the Apple page too. Do you think we should move the Known Limitations to a different page instead? In that case I would not use the collapsable troubleshooting list yet, because it would only be a single point for each.

[jas-kas]

I think known limitations can still fall within in the Troubleshooting context/page!

For the JS troubleshooting docs, we use it in a way that lists known limitations as well

[Copilot]

Pull Request Overview

This PR adds documentation for a known limitation where AVFoundation views and layers cannot be captured in iOS Session Replay, addressing user confusion about why video content and camera previews don't appear in replays.

• Adds a new "Known Limitations" section explaining AVFoundation capture limitations
• Clarifies that unmaskedViewClasses configuration cannot override this limitation
• Provides reference to GitHub issue for tracking progress on potential solutions

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[philprime]

@jas-kas I updated it so that it fits the new collapsable list.

[jas-kas]

@philprime looks like latest deploy failed so I can't see the latest Vercel preview with your changes :/

[jas-kas]

ok, the deploy is back. visual changes look good!