GuidesAPI GuideChangelog
Log In
Guides

E. PIP로 바로 시작하기

시청자가 방송을 보기 전에 앱이 원하는 화면에서 PIP 로 바로 시작합니다. 라이브 ID 를 앱이 정하면 showFloatingPlayer() 를, 방송 선택까지 SDK 에 맡기면 setOnAirInit() 을 씁니다.

E. PIP로 바로 시작하기 — 소스라이브 플레이어 iOS SDK
⏱ 예상 소요 시간: 10~20분 (방식에 따라 상이)
📋 사전 조건: 2. 플레이어 실행하기
앱 홈 화면 위에 떠 있는 작은 플레이어
▲ 앱 홈 화면 위에 떠 있는 작은 플레이어
PIP로 전환하기와의 차이

둘 다 작은 창으로 보이지만 시작하는 시점이 다릅니다.
D. PIP로 전환하기 는 보던 플레이어를 작은 창으로 줄이는 것이고, 이 페이지는 보기 전에 앱이 원하는 화면에서 PIP 로 바로 시작하는 것입니다.
라이브 ID 를 앱이 정할 때는 SauceClient.showFloatingPlayer() 를 씁니다.
방송 선택까지 SDK 에 맡길 때는 전용 API setOnAirInit() 을 씁니다 → 진행 중인 방송으로 띄우기

D. PIP로 전환하기E. PIP로 바로 시작하기
시작 시점시청자가 방송을 보던 중시청자가 방송을 보기 전
시작하는 쪽시청자 — PIP 버튼
또는 앱이 startPIPMode() 호출
앱 코드
쓰는 APIPIPKit.show · startPIPMode()showFloatingPlayer()
또는 setOnAirInit()
목적보던 방송 이어 보기진행 중인 방송으로 시청자 유입

작은 창은 한 번에 하나만 뜹니다. PIP 창이 떠 있을 때 이 페이지의 방식으로 띄우면 기존 PIP 창이 닫히고 새 창만 남습니다.

연동하기

홈 화면이 나타날 때 라이브 ID 를 넘겨 바로 작은 창으로 띄웁니다. 지금 맨 앞 화면 위에 뜹니다.
작은 창에는 확대 · 음소거 · 닫기 버튼이 있고, 영상을 누르면 재생과 일시정지가 바뀝니다. 확대 버튼을 누르면 전체 플레이어가 됩니다.

Swift
class HomeVC: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        guard !PIPKit.isActive else { return }   // 이미 떠 있으면 중복 실행 방지

        SauceClient.showFloatingPlayer(
            broadcastID: "라이브 ID",
            token: userToken                       // nil 이면 게스트
        )
    }
}
⚠️ 중복 실행을 반드시 막으세요 — 이미 떠 있는 상태에서 showFloatingPlayer() 를 다시 부르면 기존 창을 닫고 새로 띄웁니다. 홈 화면은 여러 번 나타나므로 PIPKit.isActive 로 확인하는 코드가 필요합니다.
📘 앱 코드로 닫거나 상태를 확인할 수 있습니다. SauceClient.closePIPMode() 로 닫고, SauceClient.getFloatingState() 로 지금 상태를 봅니다. 상태가 바뀔 때마다 받으려면 SauceClient.setFloatingListener(_:) 를 등록합니다 → Event handler
표시할 방송 선택

라이브 ID 를 앱이 정할지, SDK 가 고를지에 따라 쓰는 API 가 다릅니다.

앱이 라이브 ID 지정SDK 가 자동 선택
쓰는 APIshowFloatingPlayer()setOnAirInit()
띄울 방송앱이 정한 라이브 IDLIVE 방송 중 가장 최근에 시작한 하나
기본 모양확대 · 음소거 · 닫기 버튼, 소리 켜고 시작LIVE 뱃지와 닫기 버튼, 음소거로 시작

라이브 ID 를 앱이 정할 때는 아래 순서로 준비합니다.

  • 1
    편성이 정해져 있다면 — 라이브 ID 를 앱에 내려 주는 자사 API 를 만들어 홈 진입 시 조회합니다.
  • 2
    방송이 없을 때 — 플로팅을 띄우지 않습니다. 진행 중이 아닌 라이브 ID 로 띄우면 빈 화면이 보입니다.
  • 3
    방송 목록·편성 정보가 필요하면 담당자에게 문의해 주세요.
진행 중인 방송으로 띄우기

setOnAirInit() 은 파트너의 LIVE 방송 중 가장 최근에 시작한 방송 하나를 SDK 가 골라, LIVE 뱃지가 붙은 작은 창으로 띄웁니다.

Swift
// SauceClient 초기화 이후 호출합니다
SauceClient.setOnAirInit()

위치·크기·뱃지 이미지를 정하고, 선택 결과와 상태를 받으려면 옵션과 리스너를 함께 씁니다.

Swift
final class FloatingObserver: SauceFloatingListener {
    func onStateChanged(_ state: SauceFloatingState, broadcastID: String?) {
        // .full / .mini / .systemPIP / .closed
    }
    func onFloatingClosed(broadcastID: String?, reason: SauceFloatingCloseReason) {
        // .user / .host / .broadcastEnded
    }
}

let observer = FloatingObserver()
SauceClient.setFloatingListener(observer)

SauceClient.setOnAirInit(
    options: SaucePipOptions(
        width: 120,
        position: .bottomRight,
        marginVertical: 76,                           // 기본 여백 20 + 하단 탭바 56
        badge: .imageUrl("https://example.com/live-badge.gif")
    ),
    token: "발급받은 사용자 토큰"
) { result in
    switch result {
    case .selected(let broadcastID, let state): break
    case .none: break   // LIVE 방송 없음 · 조회 실패 · 초기화 전
    }
}
📘 파트너 ID 와 환경은 초기화 값을 따릅니다. 스테이지로 초기화하면 스테이지의 LIVE 방송에서 고릅니다. 초기화 전에 부르면 아무것도 띄우지 않고 바로 .none 이 옵니다. 파트너 ID 와 조회 환경을 직접 넘기는 형태는 API 에 있습니다.

작은 창은 영상만 재생합니다. 채팅·상품 등 상호작용은 없습니다.
영상을 누르면 전체 플레이어로 전환됩니다.
드래그로 옮길 수 있고, 놓은 자리에 남습니다.
옵션·결과·제어 메서드 전체 → API · 리스너 → Event handler

항목동작
방송 선택상태가 onair·warning 인 방송 중 시작 시각이 가장 최근인 하나를 고릅니다. 시작 시각이 없는 방송은 뒤로 갑니다.
목록은 호출 1회당 1회 조회합니다.
방송 교체띄운 뒤 다른 방송이 시작돼도 바뀌지 않습니다. 다시 고르려면 setOnAirInit() 을 다시 호출합니다.
동시 실행한 번에 하나의 플레이어만 띄웁니다.
다시 호출결과가 오기 전에 다시 부르면 앞 호출의 결과는 오지 않습니다.
방송 종료작은 창 동안 30초마다 방송 상태를 확인합니다. 채팅 연결로 종료 신호가 오면 2초 간격으로 최대 5번 더 확인합니다. showFloatingPlayer() 로 띄운 창도 같습니다.
방송이 VOD 로 바뀌면 닫지 않고 뱃지를 숨긴 채 VOD 로 이어서 재생하고, 변환 중이면 그대로 둡니다. 그 밖에 더 재생할 수 없게 되면 닫습니다(.broadcastEnded). 조회에 실패하면 유지합니다.
뱃지 이미지PNG·SVG·GIF(움직이는 GIF 포함)를 씁니다. JPG 이거나 3초 안에 불러오지 못하면 기본 LIVE 뱃지를 표시합니다.
크기를 정하지 않으면 높이는 최대 24pt, 너비는 이미지 비율을 따릅니다.
백그라운드작은 창 상태로 백그라운드로 가면 닫습니다(.host). 작은 창에서 시스템 PIP 로 넘어가지 않습니다.
closeOnBackground = false 면 재생을 멈추고, 돌아오면 이어서 재생합니다.
초기화SauceClient 초기화 이후에 호출합니다. 최소 지원 버전은 iOS 13 입니다.
스크롤에 따라 띄우기

스크롤 위치에 따라 띄우는 옵션은 없습니다.
앱이 스크롤을 감지해 원하는 시점에 호출합니다.

  • 1
    스크롤 위치를 감지합니다. 화면의 스크롤 리스너에서 현재 위치를 읽습니다.
  • 2
    기준을 넘으면 호출합니다. showFloatingPlayer() 또는 setOnAirInit() 을 부릅니다.
작은 창 모양 정하기

크기 · 위치 · 버튼 · 뱃지 · 테두리 · 그림자는 SaucePipOptions 로 정합니다.
앱 전체에 쓰려면 SauceClient.setPipOptions(_:) 에, 이번 창에만 쓰려면 showFloatingPlayer() · setOnAirInit() 의 options 에 넘깁니다.

Swift
// 앱 전체 기본값. 플레이어의 PIP 버튼 · startPIPMode() · options 없이 부른 showFloatingPlayer() 가 씁니다
SauceClient.setPipOptions(
    SaucePipOptions(
        width: 160,
        position: .bottomLeft,
        buttonList: [.fullscreen, .exit],              // 음소거 버튼 숨김
        borderWidth: 1,
        borderColor: "#FF8A00"
    )
)

정하지 않은 항목은 띄우는 방법마다 기본값이 다릅니다.

항목setOnAirInit그 밖(showFloatingPlayer · PIP 버튼)
크기너비 150pt, 9:16화면 너비 45%(최대 220pt), 영상 비율
가장자리 여백20pt15pt
레이아웃.badge: LIVE 뱃지와 닫기 버튼. 영상을 누르면 전체 화면.control: 확대 · 음소거 · 닫기 버튼. 영상을 누르면 재생 · 일시정지
소리음소거로 시작소리를 켜고 시작

setPipOptions(_:) 는 이미 떠 있는 창에는 적용되지 않고, 다음에 띄우는 창부터 적용됩니다.
항목 전체 → API



Did this page help you?
🏠 소스라이브 🎬 소스클립 🔗 소스링크 📢 소스애드
🧩 API 가이드
🆕 최근 업데이트
💬 도움이 더 필요하신가요?
메일로 문의 카카오톡 채널로 문의
담당자에게 문의하기

궁금한 점이나 불편했던 점을 남겨주시면 담당자가 확인 후 답변드릴게요.

가이드 챗봇
* AI를 활용해 답변해서 사실과 다를 수도 있어요. 더 궁금한 사항은 '담당자에게 문의하기'를 이용해주세요.
💡 궁금한 솔루션(예: 라이브, 링크 등)을 함께 적어주시면 더 정확한 답변을 받을 수 있어요.