iframe 연동 가이드

iframe 연동 가이드 — 소스라이브 플레이어

소스라이브 플레이어를 iframe으로 직접 삽입할 때 발생할 수 있는 성능 저하, 브릿지 이벤트 통신 오류, 브라우저 정책 이슈를 방지하기 위한 주의사항을 안내합니다.

⏱ 15~30분 📋 사전 조건: 플레이어 URL 확보

🚫 신규 연동을 시작한다면 이 페이지는 적합하지 않습니다.
소스라이브는 라이브러리 연동 또는 URL 연동을 권장합니다. 이 가이드는 기존에 iframe 방식으로 구현된 환경에서 주의사항과 제약을 안내하는 참고 문서입니다.

기본 iframe 삽입

브라우저 정책에 의해 자동 재생·전체 화면 등의 기능이 제한되지 않도록 allow 속성을 반드시 포함하세요.

HTML

<iframe
  id="sauce-player"
  src="https://player.sauceflex.com/broadcast/{라이브_ID}"
  width="100%"
  height="100%"
  allow="autoplay; fullscreen; picture-in-picture"
  title="Saucelive Player"
></iframe>

⚡ allow 속성에 autoplay; fullscreen; picture-in-picture를 포함하지 않으면 자동 재생이 차단되거나 전체 화면 전환이 동작하지 않을 수 있습니다.

성능 최적화 및 로딩 지연 방지

플레이어 진입 시 초기 빈 화면·로딩 지연을 줄이기 위한 세 가지 권장 사항입니다.

중첩 iframe 사용 금지

소스라이브 플레이어는 반드시 최상위 window 기준 자식 Depth 1 위치에서 직접 호출해야 합니다. 다른 iframe 내부에서 플레이어를 다시 삽입하는 중첩 구조는 지원하지 않습니다.

✅ 권장 구조

Customer Page
└ iframe (Saucelive Player)

❌ 비권장 구조

Customer Page
└ iframe
└ iframe (Saucelive Player)

🚫 중첩 iframe 사용 시 발생할 수 있는 문제: 단계별 표시 지연으로 빈 화면 노출 시간이 길어지고, 상품 클릭·플레이어 닫기 등 주요 브릿지 이벤트가 누락되거나 예상과 다르게 동작할 수 있습니다.

도메인 사전 연결 (preconnect)

부모 페이지의 <head>에 아래 태그를 추가하면 브라우저가 소스라이브 서버와 미리 연결을 맺어 플레이어 로딩 속도를 단축할 수 있습니다.

HTML

<link rel="preconnect" href="https://player.sauceflex.com/" />

💡 preconnect 대상은 실제 iframe src에 사용하는 플레이어 도메인과 동일해야 합니다.

Short URL 사용 비권장

단축 URL(sflex.us 등)은 내부적으로 301/302 리다이렉트가 발생하여 추가 대기 시간을 유발합니다. iframe src에는 리다이렉트가 없는 최종 목적지 Full URL을 직접 사용하세요.

❌ 비권장

https://sflex.us/{단축코드}

✅ 권장

https://player.sauceflex.com/broadcast/{라이브_ID}

양방향 통신 (브릿지 이벤트)

플레이어의 닫기, 상품 클릭 등 이벤트를 부모 페이지에서 처리하려면 message 리스너를 등록해야 합니다. iframe 환경에서도 동일한 방식으로 동작합니다.

JavaScript

window.addEventListener('message', (event) => {
  try {
    const { key, params } = JSON.parse(event.data)

    switch (key) {
      case 'sauceflexMoveExit':
        // 플레이어 닫기 처리
        document.getElementById('sauce-player').style.display = 'none'
        break
      case 'sauceflexMoveProduct':
        // 상품 클릭 처리
        if (params.linkUrl) window.location.href = params.linkUrl
        break
      // 추가 이벤트는 브릿지 이벤트 레퍼런스 참고
    }
  } catch (e) { /* 비형식 메시지 무시 */ }
})

⚡ 모든 이벤트 목록과 데이터 구조는 브릿지 이벤트 레퍼런스를 참고하세요.

UI 및 스크롤 옵션

스크롤 잠금 해제 (unlockIframeScroll)

플레이어는 기본적으로 내부 스크롤이 잠겨 있습니다. 부모 페이지 레이아웃에 따라 스크롤이 필요한 경우 아래 URL 파라미터를 추가하세요.

파라미터

unlockIframeScroll=true

적용 예시

          https://player.sauceflex.com/broadcast/{라이브_ID}?unlockIframeScroll=true
        

브라우저 환경별 제약사항

iframe 방식은 브라우저 보안 정책의 영향을 직접 받습니다. 아래 제약사항을 사전에 파악하고 대응 방안을 준비하세요.

🍪

서드파티 쿠키 차단 (ITP)iOS Safari

iOS Safari는 크로스 오리진 iframe 내 서드파티 쿠키를 기본으로 차단합니다. 플레이어가 쿠키 기반으로 로그인 세션·사용자 상태를 유지하는 경우, iOS 환경에서는 해당 정보가 저장되지 않아 매 접속 시 인증이 초기화될 수 있습니다.

💾

localStorage / sessionStorage 접근 불가크로스 오리진 전체

크로스 오리진 iframe 내에서는 부모 페이지의 localStorage·sessionStorage에 접근할 수 없습니다. 플레이어와 부모 페이지 간 상태 공유가 필요한 경우 postMessage를 통한 명시적 메시지 전달 방식으로 대체해야 합니다.

🪟

팝업·새 창 차단Chrome · Safari

iframe 내에서 window.open()을 호출하면 브라우저 팝업 차단 정책에 의해 새 창이 열리지 않을 수 있습니다. 상품 상세 페이지 이동 등 새 창이 필요한 경우, 부모 페이지에서 브릿지 이벤트를 수신해 직접 처리하는 방식으로 구현해야 합니다.

🤖

Android WebView 쿠키 미저장Android 앱 내 WebView

Android 앱 내 WebView에서 iframe을 사용할 경우, 기본 설정으로는 쿠키가 저장되지 않습니다. CookieManager.setAcceptThirdPartyCookies(webView, true)를 명시적으로 설정해야 쿠키가 정상 저장됩니다.

연동 전 체크리스트

iframe 연동 완료 후 아래 항목을 최종 점검하세요.

✅ iframe 연동 체크리스트

중첩 iframe 구조를 사용하지 않았나요?
플레이어는 최상위 페이지에서 직접 삽입되어야 합니다.

iframe src에 Full URL을 사용했나요?
단축 URL(sflex.us 등) 대신 최종 목적지 URL을 사용하세요.

iframe에 allow 속성을 포함했나요?
autoplay; fullscreen; picture-in-picture가 모두 포함되어야 합니다.

부모 페이지에 브릿지 이벤트 리스너를 등록했나요?
sauceflexMoveExit 등 주요 이벤트를 처리하는 message 리스너가 필요합니다.

스크롤이 필요한 경우 unlockIframeScroll=true를 적용했나요?
기본값은 스크롤 잠금 상태입니다.

성능 최적화를 위해 preconnect를 추가했나요?
선택 사항이지만 플레이어 로딩 속도 향상에 효과적입니다.

다음 단계

🚨 에러 가이드 — 오류 코드별 원인과 해결 방법

→