플레이어 API

플레이어를 제어하고 이벤트를 수신하는 방법은 두 가지입니다. <pellio-player> 웹 컴포넌트를 사용하거나, iframe 임베드에서 postMessage를 사용합니다.

웹 컴포넌트

동영상의 Embed & share 탭에서 Web component를 선택하거나 직접 작성하세요.

<script src="https://play.pellio.io/assets/embed.js" async></script>
<pellio-player video="VIDEO_ID" muted start="30" color="#e8492f"></pellio-player>

• 속성: video(재생목록은 playlist), start, color, title, 고정 크기를 위한 width와 height 또는 aspect-ratio(기본값 16/9), controls="false", 그리고 플래그 autoplay, muted, loop, captions, background, resume, dnt가 있습니다. 플레이어는 스크롤해서 화면에 보일 때 로드되며, 바로 로드하려면 eager를 추가하세요.
• 팝오버: popover를 추가하면 재생 버튼이 있는 썸네일이 표시되고, 태그 안에 직접 텍스트나 버튼을 넣을 수도 있습니다. 클릭하면 플레이어가 라이트박스로 열립니다.
• 메서드: play(), pause(), seek(seconds), mute(true|false), volume(0–1), rate(n), identify(email)
• 프로퍼티(읽기 전용): currentTime, duration, paused
• 이벤트: 아래의 모든 플레이어 이벤트가 요소에서 pellio:<event>로 발생하며, 메시지는 event.detail에 담깁니다. 팝오버는 pellio:open과 pellio:close도 발생시킵니다.

const player = document.querySelector('pellio-player');
player.addEventListener('pellio:progress', (e) => console.log(e.detail.percent));
player.seek(42);

웹 컴포넌트는 동영상 이벤트를 Google Analytics와 Tag Manager로도 보냅니다(분석 참고).

postMessage 명령

const player = document.querySelector('iframe').contentWindow;
player.postMessage({ pellio: true, method: 'play' }, '*');
player.postMessage({ pellio: true, method: 'seek', value: 42 }, '*');

method	value
play, pause	없음
seek	초(건너뛰기 금지가 켜져 있으면 이미 시청한 범위 안에서만)
mute	true 또는 false
volume	0~1
rate	재생 속도(예: 1.5, 프리셋의 속도 제한까지)
identify	시청자의 이메일(분석에서 이름으로 표시하고 양식을 건너뛰기 위함)

이벤트

플레이어는 상위 페이지로 { pellio: true, id, title, event, currentTime, duration }를 보내며, 일부 이벤트에는 추가 필드가 포함됩니다.

event	발생 시점
ready, play, pause, seeked, timeupdate, ratechange, volumechange	video 요소가 해당 이벤트를 발생시킬 때
ended, complete	동영상이 끝에 도달했을 때(둘이 함께 발생)
progress	재생 위치가 25, 50, 75, 90%를 지났을 때(percent). 고유 시청 초가 아니라 위치 기준입니다.
interaction	인터랙션이 표시, 클릭, 건너뛰기 되었을 때(interaction, type, kind: view, click, skip)
lead	양식이 제출되었을 때(interaction, email)
chapter	챕터를 선택했을 때(chapter, t)
download	시청자가 동영상을 다운로드했을 때
logo	시청자가 프리셋의 로고를 클릭했을 때(href)
transcript	스크립트 패널이 열리거나 닫혔을 때(open)
attention	“Still watching?” 확인이 표시되거나 응답되었을 때(prompt)
cast	TV로 캐스팅이 시작되거나 중지되었을 때(state)

window.addEventListener('message', (e) => {
  if (e.data?.pellio && e.data.event === 'progress') console.log(e.data.id, e.data.percent);
});

재생목록 임베드(/p/…)는 같은 이벤트에 playlist 필드를 더해 보내며, 동영상이 선택되면 select도 보냅니다. 재생목록 임베드는 명령을 받지 않습니다.