YouTube embeds broken on iOS (Error 153)

Problem

YouTube iframe embeds show Error 153 on iOS native builds. This is caused by WKWebView not sending valid HTTP Referer headers from the capacitor:// origin — YouTube rejects embeds without a valid Referer.

This affects all views using EmbeddedVideo / EmbeddedVideoCard (react-player):

  • BLISS 2026 About (BlissAboutView)
  • BLAZE About (BlazeAboutView)
  • Introduction Video (AppIntroVideoView)
  • BLISS Tickets (BlissTicketsView)
  • AFOG (AppAfogView)

Not broken on: Android (uses https:// scheme by default), web/dev server.

Root Cause

  • iOS Capacitor serves from capacitor://localhost
  • WKWebView does not send Referer headers for cross-origin iframe requests from custom URL schemes
  • YouTube now requires a valid Referer to load embedded videos
  • No workaround exists at the WebView level (confirmed: WKURLSchemeHandler can't intercept https requests, youtube-nocookie.com has same restriction, IFrame API origin param only controls postMessage)

Solution

Platform-specific behavior in EmbeddedVideo.tsx:

  • Web / Android: Keep existing inline react-player embed (works fine)
  • iOS native: Show YouTube thumbnail image + play button overlay → tap opens video in @capacitor/browser (Safari View Controller modal). User taps "Done" to return to app.

Thumbnail URL pattern: https://img.youtube.com/vi/{VIDEO_ID}/hqdefault.jpg

The useNavigateExternal hook already wraps @capacitor/browser. Platform detection available via @capacitor/core (Capacitor.getPlatform()).

Stretch goal

Evaluate removing react-player entirely if all YouTube usage can be handled by thumbnail + Browser.open on all platforms. Would remove a 39KB lazy chunk + one dependency.

References

Edited by Kallisti