에러 가이드

에러 가이드 — 소스라이브 플레이어

소스라이브 플레이어 연동 중 자주 발생하는 이슈와 해결 방법을 정리합니다. 증상에 맞는 항목을 확인하세요.

빠른 진단 — 증상으로 찾기

증상	가장 흔한 원인	바로가기
채팅 입력 시 UI가 잘리거나 밀림 (iOS)	viewport 메타 태그 누락 또는 오설정	iOS · UI 해결 →
JWT를 설정했는데 게스트로 표시됨	토큰 payload 필드 누락 또는 형식 오류	JWT · 인증 해결 →
상품 클릭·쿠폰·로그인 버튼이 무반응	자사몰에 브릿지 이벤트 리스너 미구현	브릿지 이벤트 해결 →
브릿지 이벤트가 전혀 수신되지 않음	리스너 등록 위치 오류 또는 중첩 iframe 구조	FAQ에서 확인 →
플로팅에서 전체 화면 전환이 안 됨	전체화면·종료 전역 콜백 미정의	FAQ에서 확인 →

📱

iOS · UI

채팅 입력 시 UI가 잘리거나 밀리는 현상

iOS Safari / WebView에서 키보드 등장 시 레이아웃 깨짐

원인

viewport 메타 태그가 누락되거나 잘못 설정된 경우 발생합니다. iOS에서 키보드가 올라올 때 핀치 줌이 활성화되어 있으면 뷰포트가 의도치 않게 변형됩니다.

해결 방법

핀치 줌을 비활성화하고 뷰포트 너비를 디바이스 화면 너비와 동일하게 설정합니다. 플레이어를 삽입하는 페이지의 <head>에 아래 메타 태그를 추가하세요.

HTML — <head>에 추가

<meta name="viewport"
      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, user-scalable=no">

⚡ user-scalable=no 설정은 핀치 줌을 전면 비활성화합니다. 접근성 요구사항이 있는 서비스라면 플레이어 영역에만 제한적으로 적용하는 방식을 검토하세요.

🔐

JWT · 인증

JWT 토큰을 설정했는데 게스트로 로그인됨

setMemberToken() 적용 후에도 로그인 하지 않은 상태로 표시되는 경우

원인

JWT 토큰 생성 과정에서 Header 설정 오류, 잘못된 서명 키, 필수 payload 누락 등이 있으면 서버에서 토큰 검증에 실패하여 게스트로 처리됩니다.

적용 코드 확인

JavaScript — 올바른 적용 순서

window.SauceLiveLib.setInit({ broadcastId: liveId })
window.SauceLiveLib.setMemberToken(jwt)   // setInit 이후 호출
window.SauceLiveLib.load('sauce_live')    // 마지막에 load()

체크리스트 — 아래 항목을 순서대로 확인하세요

JWT Header에 알고리즘 정보를 정확히 설정했나요?
"typ": "JWT"와 "alg": "RS256" 두 필드가 모두 포함되어야 합니다.

JWT Header

{ "typ": "JWT", "alg": "RS256" }

모비두에서 전달받은 PEM 키로 서명했나요?
직접 생성한 키가 아닌, 소스라이브 어드민에서 발급받은 RS256 개인키(PEM)를 사용해야 합니다.

토큰을 Base64로 인코딩했나요?
JWT는 Header · Payload · Signature 각각을 Base64URL로 인코딩한 후 .으로 이어 붙여야 합니다.

필수 payload 필드가 모두 포함되어 있나요?
아래 표에서 Required: Y 항목이 누락되면 인증에 실패합니다.

JWT Payload 필드

파라미터	타입	필수	기본값	설명
partnerId	string	필수	—	발급받은 파트너사 ID
memberId	string	필수	—	파트너사 회원의 고유 ID
nickName	string	필수	—	채팅 시 표시되는 닉네임. 실명 사용 시 마스킹 처리 권장
memberType	string	필수	—	시청자 타입 — 회원: `"1"`, 비회원: `"0"`
age	string	선택	etc	통계용 연령대 — `"10"` / `"20"` / `"30"` / `"40"` / `"50"` / `"60"` / `"etc"`
gender	string	선택	e	통계용 성별 — 남성: `"m"`, 여성: `"w"`, 기타: `"e"`

⚡ JWT 토큰 생성 전체 과정은 사용자 인증 가이드를 참고하세요.

🔗

브릿지 이벤트

상품 클릭 또는 일부 기능이 동작하지 않음

상품 링크 이동 불가, 쿠폰 다운로드 무반응, 로그인 버튼 미동작

원인

상품 클릭, 쿠폰, 로그인 등 일부 기능은 자사몰에서 브릿지 이벤트 리스너를 직접 구현해야 동작합니다. 리스너가 없으면 플레이어가 이벤트를 전송해도 아무런 처리가 이루어지지 않습니다.

해결 방법

브릿지 이벤트 가이드를 참고하여 window.addEventListener('message', ...)를 구현하세요.

JavaScript — 최소 브릿지 이벤트 구현 예시

window.addEventListener('message', (e) => {
  if (typeof e.data !== 'string') return
  const { key, params } = JSON.parse(e.data)

  switch (key) {
    case 'sauceflexMoveProduct':
      if (params.linkUrl) window.location.href = params.linkUrl
      break
    case 'sauceflexMoveLogin':
      window.location.href = `/login?returnUrl=${window.location.href}`
      break
    // 필요한 이벤트를 추가하세요
  }
})

⚡ 전체 이벤트 목록과 데이터 구조는 브릿지 이벤트 연동 및 브릿지 이벤트 레퍼런스를 참고하세요.

다음 단계

💬 자주 묻는 질문 — 통합 연동 시 자주 겪는 문제 모음

→