PlaynPlay
PlaynPlay

웹 연동 개요

웹 강의실에 PlaynPlay를 붙일 때
PM이 정할 것과 개발팀에 넘길 것

웹 연동은 고객사 웹 페이지가 학습자 PC의 PlaynPlay App을 불러 재생하는 방식입니다. 스크립트 구성, 실행 타입, 영상마다 넘기는 값의 업무상 뜻, 커스텀 페이지 기능을 기획자 눈높이로 풀고 개발 착수 전에 내려야 할 결정을 모았습니다.

최종 수정

웹 연동을 표현한 PlaynPlay 일러스트
Structure

스크립트 두 개와 호출 세 가지

웹 쪽 작업은 페이지에 스크립트 두 개를 넣고 버튼에 호출을 연결하는 데서 시작합니다. 호출은 모두 비동기 함수입니다.

요소 하는 일 PM이 챙길 것
playnplay_config.js 고객사 경로에 두는 설정 파일. 지금 문서에 있는 설정은 앱 최소 버전(minVersion) 하나입니다. 공통 페이지 템플릿에서 agent.js 앞자리에 고정
agent.js playnplay 객체를 제공합니다. 일반 고객사는 app.playnplay.com, CDNetworks 고객사는 pnp-appdn.cdnetworks.com에서 불러옵니다. 계약 형태에 맞는 도메인 확인
launch() 실행 타입, 미디어 아이템 또는 주소, 창 너비·높이를 받아 앱을 엽니다. 버튼마다 실행 타입 지정
download() 미디어 아이템 하나나 여러 개를 다운로드 항목으로 넘깁니다. 차시 일괄 다운로드 버튼 제공 여부
getDeviceInfo() 브라우저가 실행 중인 장치의 플랫폼, OS 버전, 아키텍처, 모델을 돌려줍니다. 지원 범위 안내와 문의 접수에 활용
Launch Types

실행 타입은 버튼의 목적대로 고릅니다

launch()의 첫 번째 값이 앱이 열린 뒤 무엇을 할지 정합니다.

  • Streaming

    동영상 재생

    강의실 화면은 그대로 두고 재생만 앱에서 합니다. 수강 버튼 대부분이 여기에 해당합니다.

    • 미디어 아이템이나 주소 문자열로 실행
    • 창 크기는 options의 width, height
  • Downloading

    동영상 다운로드

    오프라인 수강을 허용하는 과정에 둡니다. 다운로드한 파일의 경로 표시 값은 metadata의 downloadPath로 넘깁니다.

    • 오프라인 재생 기한은 DRM 설정에서 지정
    • 여러 차시는 download()로 묶어 요청
  • OpeningPage

    커스텀 페이지 열기

    고객사가 만든 강의 목록·학습 화면 웹 페이지를 PlaynPlay App 창 안에 띄웁니다. 페이지 안 재생과 북마크는 아래 API로 다룹니다.

    • 페이지는 startService()로 보안 서비스 실행
    • 링크·창 동작을 미리 설계
MediaItem

영상마다 넘기는 값을 업무 언어로

MediaItem은 영상 한 편의 재생 조건 묶음입니다. 값마다 정하는 사람을 먼저 지정해 두면 개발팀이 기다리는 시간이 줄어듭니다.

항목 업무상 뜻 정하는 사람
url 미디어 서버에 올린 패키징 파일의 주소 콘텐츠 운영
drm.appId 콘솔에서 만든 서비스(App)의 식별값 개발
drm.userId 누가 보는지. 라이선스와 모든 보고에 붙는 사용자 기준 개발, 사업
drm.userData 강좌 ID, 수강 신청 ID처럼 Callback 보고에 그대로 돌아올 값 기획
drm.offlineAccessPeriod 다운로드본을 볼 수 있는 시간(초). null이면 기한 없이 열리고, 0이면 오프라인에서 열리지 않음 사업
seekable 건너뛰기 허용 여부. 기본은 허용 사업
disablePlaybackRate 배속 금지 여부. 기본은 배속 허용 사업
startTime 이어보기 시작 위치(초). syncedAt를 붙이면 그 시각과 기기에 저장된 오프라인 재생 시점을 견줘 나중 값으로 시작 기획
subtitles 자막 주소, 언어, 표시 이름, 자동 선택·표시·숨김 콘텐츠 운영
metadata 모바일 플레이어 타임바에 보일 제목, 썸네일 주소, 다운로드 경로 표시 값 콘텐츠 운영
clipping 원본에서 시작·끝 위치 사이만 재생. 미리보기 구간에 사용 사업
useBookmarkCallback 켜면 북마크를 고객사 DB와 주고받고, 끄면 PlaynPlay 저장 방식을 씀 기획
returnUrl 리턴 URL. 문서에 동작 설명이 없어 쓰기 전에 Newin과 확인 개발

userData와 진도 값의 관계는 진도 데이터 설계, 미리보기 구간 운영은 미리보기 구간 재생에 있습니다.

Version · Device · CDN

앱 버전, 기기 정보, CDN 경로

오픈 뒤 문의가 몰리는 세 가지를 연동 단계에서 정리합니다.

  • minVersion

    앱 최소 버전

    값은 "latest" 아니면 "1.x.x" 꼴의 버전 번호입니다. 이 값 이상으로 설치된 앱에는 알림이 나가지 않습니다. 설치 권한이 제한된 사내 PC가 많다면 검증한 번호로 고정하고, 필요한 수정이 담긴 버전이 나올 때 올리기를 권합니다.

  • getDeviceInfo

    학습자 기기 정보

    장치의 OS와 버전을 읽어 지원 범위(Windows 10, macOS 11 이상) 밖 사용자 안내와 문의 대응에 씁니다. 고객센터 문의 양식에 자동으로 붙이면 원인 확인이 빨라집니다. 앱을 설치하기 전에도 값이 오는지는 검수 때 확인하세요.

  • CDNetworks

    전용 도메인과 샘플

    CDNetworks 고객사는 agent.js와 서비스 스크립트를 전용 도메인에서 불러오고 샘플 묶음도 따로 받습니다. Android·iOS SDK도 2026년 1월에 CDNetworks 고객사 API 도메인을 분리했습니다.

Custom Page API

커스텀 페이지에서 쓰는 기능

OpeningPage로 연 고객사 페이지는 아래 기능을 씁니다. 기획 칸은 화면 설계서에 미리 반영할 내용입니다.

기능 하는 일 기획 포인트
startService() App ID와 서비스 스크립트 경로로 보안 서비스를 시작합니다. 개발툴을 쓰려면 반드시 호출합니다. 스크립트 위치와 scope. 기존 서비스 워커가 있으면 거기에 추가
video 요소의 open() 페이지 안 video 요소에서 미디어 아이템이나 주소를 엽니다. 강의 화면 레이아웃을 페이지 디자인대로 유지
getBookmarks() 저장된 북마크를 가져오고 추가, 삭제, 제목 수정을 합니다. 북마크 목록을 페이지에 직접 그릴지
onSessionError 라이선스, 세션, 기기, 권한, 재생 제한 등 12가지 거부 원인을 받습니다. 원인별 안내 문구와 다음 행동 버튼
playnplay.close() 앱을 종료합니다. 1.0.31에 추가됐습니다. 학습 종료 버튼 위치
window.open, form target 1.0.31부터 앱 안 새 창으로 열리고, 외부 브라우저는 target "_external"로 엽니다. 결제, 설문, 외부 자료 링크를 어디서 열지
getDeviceId() 장치 ID를 가져옵니다. 기기 관련 문의 접수 때 함께 수집
openDevTools() 개발툴을 엽니다. 문서는 디버깅 용도로만 쓰라고 권합니다. 운영 배포 전 호출 코드 제거를 검수 항목에 포함

함수별 파라미터 원문은 커스텀 페이지 문서에 있습니다.

Acceptance

샘플에서 시작하는 검수 순서

우리 코드를 올리기 전에 공개 샘플로 기준 동작을 먼저 잡아 두면, 문제가 생겼을 때 원인이 환경인지 코드인지 바로 갈립니다.

  1. 테스트 페이지 열기

    샘플 문서에 있는 두 테스트 페이지(재생·다운로드, 커스텀 페이지)를 사내 표준 PC에서 엽니다. 여기서 막히면 PC 환경부터 봅니다.

  2. 샘플 묶음 띄우기

    계약 형태(일반, CDNetworks)에 맞는 샘플 묶음을 받아 App ID와 영상 주소만 바꿉니다. Callback 응답은 서버 사이드 샘플로 맞춥니다.

  3. 정책 값 바꿔 보기

    같은 영상을 seekable, disablePlaybackRate, offlineAccessPeriod만 바꿔 다시 열고 차이를 기록합니다.

  4. 페이지 로그 확인

    디버깅 툴(macOS arm64·x86_64, Windows x86_64·x86)로 앱 안에서 도는 커스텀 페이지의 콘솔 로그를 봅니다.

  5. 앱 버전 기록

    검수에 쓴 PlaynPlay App 버전을 적고 변경 이력과 대조해 minVersion 값을 정합니다.

테스트 페이지와 샘플은 샘플 문서, 디버깅 툴은 디버깅 문서, 앱 버전별 변경은 PlaynPlay App 변경 이력에 있습니다.

PM Decisions

개발 착수 전에 PM이 정할 것

아래 표를 착수 회의 안건으로 쓰세요. 결정이 비어 있으면 개발 중 같은 질문이 다시 돌아옵니다.

결정 선택지 판단 기준
연동 범위 재생만 앱에서, 또는 학습 화면 전체를 커스텀 페이지로 기존 강의실 화면을 유지할지
다운로드 제공 제공 안 함, 차시별, 강좌 일괄 이동 중 학습 수요와 콘텐츠 계약 조건
오프라인 기한 제한 없음, 0, 초 단위 값 수강 기간과 맞출지
시청 규칙 과정별 건너뛰기·배속 허용 여부 진도 인정 기준이 있는 과정 목록
이어보기 기준 서버가 준 위치만, 또는 syncedAt로 기기 기록과 비교 한 사람이 여러 기기로 수강하는지
북마크 저장 PlaynPlay 저장 방식, 고객사 DB 다른 서비스와 북마크를 함께 써야 하는지
userData 구성 강좌 ID, 차시 ID, 수강 신청 ID 진도를 집계하는 단위
앱 최소 버전 latest, 번호 고정 학습자 PC의 설치 권한
플레이어 창 크기 launch() 옵션의 너비·높이 지정 여부 강의 영상 비율과 학습자 화면 크기
스크립트 도메인 일반 경로, CDNetworks 전용 도메인 현재 쓰는 CDN 계약
모바일 브라우저 사용자 Agent 문서는 실행 절차가 Windows, macOS, iOS, Android에서 같다고 적고 있습니다. 모바일 쪽 설치 앱과 동선은 문서에 없음 — Newin과 확인

앱 연동을 함께 검토한다면 앱 연동 개요, 일정과 담당은 도입 실행 가이드를 보세요.

웹 연동 FAQ

  • 영상 주소 문자열만 넘겨도 재생되나요?

    launch()는 미디어 아이템 대신 URL이나 문자열도 받습니다. 다만 App ID, 사용자 ID, userData 같은 DRM 설정은 미디어 아이템의 drm 항목에 담기므로, 권한 확인과 진도 보고가 필요한 강의는 미디어 아이템으로 실행하기를 권합니다.

  • 설정 파일은 페이지마다 따로 두나요?

    공통 경로 하나에 두기를 권합니다. 지금 문서의 설정 항목은 minVersion 하나지만, 값을 바꿀 때 모든 강의 페이지를 고치지 않아도 됩니다.

  • 다운로드한 파일 이름은 어떻게 보이나요?

    실행 타입이 다운로드일 때 metadata의 downloadPath로 다운로드 파일의 경로 표시 값을 넘깁니다. 강좌명과 차시 순서를 담은 규칙을 정해 두면 학습자가 받은 파일을 찾기 쉽습니다.

Get Started

PlaynPlay 도입을 위한
기술적 지원과 서비스를 제공합니다.

제품 문의부터 데모 시연까지, 모든 지원을 위해 세일즈 및 기술 지원 팀이 준비되어 있습니다.

  • 제품 및 도입 문의

    도입 범위, 일정, 견적을 상담합니다. 서비스 형태와 사용자 규모를 알려주시면 맞는 연동 방식과 보안 설정을 제안합니다.

  • Trial 신청

    PlaynPlay의 기능을 먼저 테스트해 보세요. 트라이얼 기간 동안 귀사의 제품과 PlaynPlay를 연동하고 성능과 기능을 직접 검증할 수 있습니다.

  • PlaynPlay 기술 문의

    SDK 연동, Callback URL 설계, DRM 패키징 중에 생기는 질문에 기술팀이 답합니다. 공개된 개발 문서와 샘플 프로젝트도 함께 확인하세요.