iframe 연동

iframe 연동 — 소스클립 플레이어

⏱ 예상 소요 시간: 10분

📋 사전 조건: 플레이어 주소 확보

이 페이지의 위치

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

	라이브러리	URL 연동	`iframe`
플로팅	지원	미지원	미지원
브릿지 이벤트 페이로드	객체	JSON 문자열	JSON 문자열
브릿지 이벤트 수신부	동일 페이지 함수	앱 웹뷰	부모 창 `message`
신규 연동	권장	권장	비권장

기본 삽입

플레이어 주소를 src 로 넣습니다. 쓸 수 있는 쿼리 파라미터는 URL 연동과 같습니다.

html

<iframe
  src="https://player.sauceclip.com/player?partnerUniqueId=파트너 ID&clipId=클립 ID"
  allow="autoplay; fullscreen; picture-in-picture"
  style="width: 100%; height: 100%; border: none;"
></iframe>

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

브릿지 이벤트 받기

플레이어는 부모 창으로 message 를 보냅니다. 데이터는 { key, params } 형태의 JSON 문자열입니다.

javascript

window.addEventListener('message', (e) => {
  if (typeof e.data !== 'string') return

  let key
  let params

  try {
    const data = JSON.parse(e.data)
    key = data.key
    params = data.params
  } catch (_error) {
    return
  }

  switch (key) {
    case 'sauceclipMoveProduct':
      window.location.href = params.linkUrl
      break
    case 'sauceclipMoveExit':
      window.history.back()
      break
    default:
  }
})

📍 params 는 이미 파싱된 객체입니다. 값이 없는 이벤트에서는 null 입니다.

⚠️ message 는 다른 스크립트도 보냅니다. e.data 가 문자열인지 확인하고 파싱을 try 로 감싸 다른 메시지에서 예외가 나지 않게 합니다.

제약

항목	내용
중첩 `iframe`	지원하지 않습니다. 플레이어는 최상위 창의 자식 `iframe` 한 겹 안에 두어야 합니다. 중첩하면 표시가 지연되고 브릿지 이벤트가 누락될 수 있습니다.
플로팅	쓸 수 없습니다. 플로팅은 라이브러리 함수라 `iframe` 밖에서 호출할 수 없습니다.
단축 URL	리다이렉트가 한 번 더 일어나 대기 시간이 늘어납니다. `src` 에는 최종 주소를 직접 넣습니다.
링크 버튼	`sauceclipMoveLinkButton` 이 부모 창으로 전달되지 않습니다. 어드민에 설정한 방식대로 플레이어가 `iframe` 안에서 링크를 엽니다. 현재 창 이동으로 설정하면 `iframe` 안이 링크 페이지로 바뀝니다.

이벤트 목록

iframe 구성에서 받을 수 있는 브릿지 이벤트입니다.

이벤트	전송 시점
`sauceclipEnter`	플레이어 진입
`sauceclipMoveProduct`	상품 클릭
`sauceclipOnShare`	공유 클릭
`sauceclipMoveExit`	닫기 클릭
`sauceclipMoveChannel`	채널 클릭
`sauceclipPlayerError`	에러 발생

📌 각 이벤트의 페이로드는 브릿지 이벤트 레퍼런스에 있습니다.

다음 단계

WEB 개발 가이드 — 개요로 돌아가기

→