[NEXT/REACT] iOS WebView 영상 썸네일 백화 현상: 원인과 해결 방안

 

iOS 앱 내에서 웹뷰(WebView)를 사용하여 비디오 콘텐츠를 보여줄 때, 영상 썸네일이 하얗게 표시되는 '백화 현상'은 많은 개발자들이 겪는 문제입니다. 저 역시 이 문제로 고생했지만, poster 속성과 playsinline 속성을 함께 사용하는 간단한 방법으로 해결할 수 있었습니다. 이 글에서는 저와 같은 문제를 겪는 분들을 위해 iOS WebView에서 비디오 썸네일 백화 현상이 발생하는 원인을 분석하고, 이를 해결할 수 있는 효과적인 방법들을 공유하고자 합니다.

 

백화 현상의 주요 원인

iOS WebView의 비디오 썸네일 백화 현상은 주로 WKWebView의 비디오 재생 정책과 GPU 렌더링 방식 때문에 발생합니다.

1. 자동 재생(Autoplay) 정책: iOS의 Safari 및 WKWebView는 데이터 사용량으로부터 사용자를 보호하기 위해 비디오 자동 재생에 엄격한 정책을 적용합니다. video 태그에 autoplay 속성이 있더라도 사용자의 상호작용 없이는 재생이 시작되지 않는 경우가 많습니다. 썸네일은 비디오의 첫 프레임을 보여주는 방식으로 구현되는 경우가 많은데, 비디오가 실제로 재생 준비 상태가 되지 않으면 이 첫 프레임을 가져오지 못해 빈 화면(흰색 배경)이 표시될 수 있습니다.
2. 하드웨어 가속 및 렌더링 문제: WKWebView는 GPU를 사용하여 웹 콘텐츠를 렌더링하여 성능을 최적화합니다. 하지만 특정 상황에서 video 태그를 렌더링하는 과정에서 GPU와의 통신 오류나 버그로 인해 비디오 콘텐츠(썸네일 포함)가 올바르게 그려지지 않는 경우가 발생할 수 있습니다. 특히 CSS 변환(transform), 투명도(opacity) 등의 속성이 비디오 요소에 적용될 때 문제가 발생할 가능성이 높습니다.
3. poster 속성 미지정 또는 로딩 실패: HTML video 태그의 poster 속성은 비디오가 로드되기 전에 표시될 이미지(썸네일)를 지정하는 역할을 합니다. 만약 이 poster 속성이 지정되지 않았거나, 지정된 이미지 URL이 유효하지 않거나, 네트워크 문제로 이미지 로딩에 실패하면 비디오는 썸네일 없이 빈 상태로 표시되어 백화 현상처럼 보일 수 있습니다.

 

해결 방안

이러한 문제를 해결하기 위한 몇 가지 효과적인 방법들이 있습니다.

1. poster 속성 적극 활용

가장 간단하고 확실한 방법은 video 태그에 poster 속성을 사용하여 명시적으로 썸네일 이미지를 지정하는 것입니다.

<video
  src="your-video.mp4"
  poster="your-thumbnail-image.jpg"
  playsinline
></video>

이렇게 하면 WKWebView는 비디오의 첫 프레임을 렌더링하는 대신 지정된 이미지를 즉시 보여주므로, 비디오 로딩 여부와 관계없이 항상 썸네일을 표시할 수 있습니다. 이는 사용자 경험 측면에서도 가장 권장되는 방법입니다.

2. transform 속성으로 GPU 렌더링 강제

때로는 WKWebView의 렌더링 문제를 해결하기 위해 GPU가 새로운 레이어에서 비디오 요소를 그리도록 강제하는 방법이 효과적일 수 있습니다. CSS의 transform 속성을 활용하면 이 문제를 해결할 수 있습니다.

video {
  transform: translateZ(0);
  -webkit-transform: translateZ(0);
}

translateZ(0) 속성을 추가하면 브라우저는 해당 요소를 별도의 컴포지팅 레이어로 분리하여 처리하게 됩니다. 쉽게 말해, 비디오 요소를 다른 종이에 따로 그려서 붙이는 것처럼 GPU에 알려주는 셈이죠. 이 과정에서 멈춰있던 GPU 렌더링이 다시 활성화되면서 썸네일이 정상적으로 표시될 수 있습니다.

 

3. playsinline 속성 추가

iOS에서 전체 화면으로 전환되지 않고 인라인으로 비디오를 재생하려면 playsinline 속성이 필수적입니다. 이 속성이 없으면 비디오 재생 시 전체 화면으로 전환하려는 동작과 충돌하여 썸네일 표시에 영향을 줄 수 있습니다.

<video src="your-video.mp4" playsinline></video>

특히 웹뷰 내에서 작은 크기의 비디오 플레이어를 구현할 때는 반드시 이 속성을 추가하는 것이 좋습니다.

4. WKWebViewConfiguration 설정 변경

앱 네이티브 코드에서 WKWebView를 생성할 때, 특정 설정을 변경하여 비디오 재생 정책을 완화할 수 있습니다. WKWebViewConfiguration의 mediaTypesRequiringUserActionForPlayback 속성을 설정하여 스크립트를 통한 자동 재생을 허용하는 방식입니다.

let webConfiguration = WKWebViewConfiguration()
webConfiguration.allowsInlineMediaPlayback = true // 인라인 재생 허용
if #available(iOS 10.0, *) {
    webConfiguration.mediaTypesRequiringUserActionForPlayback = [] // 모든 미디어 타입에 대해 사용자 액션 없이 재생 허용
} else {
    webConfiguration.mediaPlaybackRequiresUserAction = false // (Deprecated)
}

let webView = WKWebView(frame: .zero, configuration: webConfiguration)

이 설정은 데이터 소모에 대한 사용자 선택권을 제한할 수 있으므로, 콘텐츠의 특성과 앱의 정책을 고려하여 신중하게 사용해야 합니다.

 

결론

iOS WKWebView에서 발생하는 비디오 썸네일 백화 현상은 대부분 poster 속성을 명확히 지정하거나, CSS transform 속성으로 GPU 렌더링을 강제하는 방식으로 해결할 수 있습니다. 가장 좋은 방법은 안정적인 썸네일 표시를 위해 poster 이미지를 항상 제공하는 것입니다. 실제로 많은 경우, 비디오에 poster 속성으로 썸네일 이미지를 명시하고 playsinline 속성을 추가하는 것만으로도 문제는 간단히 해결됩니다. 만약 동적으로 생성되는 비디오의 첫 프레임을 썸네일로 사용해야 하는 경우라면, 서버 사이드에서 비디오의 첫 프레임을 추출하여 이미지 파일로 저장하고, 그 이미지 URL을 poster로 지정하는 아키텍처를 고려하는 것이 장기적으로 더 안정적인 해결책이 될 수 있습니다.