1. 기본 iframe 삽입 방법

브라우저 정책에 의해 자동 재생 등의 기능이 제한되지 않도록 allow 속성을 포함하여 iframe을 삽입해야 합니다.

<iframe 
  id="sauce-player"
  src="https://{플레이어_도메인}/broadcast/{방송_ID}" 
  width="100%" 
  height="100%" 
  allow="autoplay; fullscreen; picture-in-picture"
  title="Saucelive Player"
></iframe>

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

플레이어 진입 시 발생할 수 있는 초기 빈 화면 및 로딩 지연을 줄이기 위한 권장 사항입니다.

2-1. 중첩 iframe 사용 금지

고객사 페이지에 iframe을 삽입한 후, 해당 iframe 내부 문서에서 다시 소스라이브 플레이어를 호출하는 중첩 iframe 구조는 로딩 지연을 유발할 수 있으므로 권장하지 않습니다.

발생 가능 문제

단계별 렌더링 지연으로 인해 초기 빈 화면 노출 시간이 길어질 수 있습니다.
상품 클릭, 플레이어 닫기 등 주요 브릿지 이벤트 수신이 누락되거나 예상과 다르게 동작할 수 있습니다.

권장 방식

소스라이브 플레이어는 반드시 최상위 Window 기준 자식 Depth 1 위치에서 직접 호출해야 합니다.

다른 iframe 내부 문서에서 다시 플레이어를 삽입하는 중첩 구조는 사용을 권장하지 않습니다.

구조 예시

권장 구조

Customer Page
 └ iframe (Saucelive Player)

비권장 구조

Customer Page
 └ iframe
     └ iframe (Saucelive Player)

2-2. 도메인 사전 연결 (preconnect)

플레이어 리소스를 다운로드하기 전에, 브라우저가 소스라이브 서버와 미리 연결을 맺도록 설정하면 접속 시간을 단축할 수 있습니다.

부모 페이지의 <head> 태그에 아래 코드를 추가해 주세요.

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

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

2-3. Short URL 사용 지양

단축 URL(sflex.us 등)은 내부적으로 리다이렉트(301/302)가 발생할 수 있으므로 사용을 권장하지 않습니다.

발생 가능 문제

리다이렉트로 인해 추가 대기 시간이 발생할 수 있습니다.
플레이어 진입 시 초기 빈 화면 노출 시간이 길어질 수 있습니다.

권장 방식

리다이렉트가 없는 최종 목적지 URL(Full URL) 을 iframe src에 직접 사용합니다.

3. 양방향 통신 (Bridge API)

플레이어의 닫기, 상품 클릭 등 동작을 감지해 부모 페이지에서 이벤트를 처리 해야 플레이어 기능을 정상적으로 사용할 수 있습니다.

window.addEventListener('message', (event) => {
  try {
    const data = JSON.parse(event.data);
    if (data.key === 'sauceflexMoveExit') {
      console.log('플레이어 닫기 및 페이지 이동 처리');
    }
  } catch (e) { /* 비형식 메시지 무시 */ }
});

관련 내용은 payload 정의 문서를 참고해 주세요.

4. UI 및 스크롤 옵션 제어

4-1. 스크롤 락(Scroll Lock) 해제

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

URL 파라미터

unlockIframeScroll=true

적용 예시

https://.../broadcast/{ID}?unlockIframeScroll=true

✅연동 전 체크리스트

아래 항목을 최종으로 확인해 iframe이 정상적으로 구성되었는지 점검해보세요.

플레이어를 중첩 iframe 구조로 삽입하지 않았나요?
iframe src에 리다이렉트 URL이 아닌 최종 목적지 URL을 사용했나요?
iframe에 allow 속성을 포함했나요?
스크롤이 필요한 경우 unlockIframeScroll=true 파라미터를 적용했나요?