개발 리드가 책임지는 범위
재생을 붙이는 코드는 짧아도, 서버 응답 규칙과 오류 처리, 버전 추종은 서비스가 살아 있는 동안 계속 남는 일입니다.
-
방식 선택
채널별 연동 방식
웹 강의실은 Agent로 PlaynPlay App을 띄우고, 자사 앱은 SDK를 넣습니다. PC 학습 화면 전체를 앱 안에 둘지는 커스텀 페이지로 정합니다.
-
빌드 요건
플랫폼 최소 사양
Android SDK는 API 수준 25(Android 7.1) 이상, iOS SDK는 Minimum Deployment 13.0, PlaynPlay App은 Windows 10·macOS 11 이상입니다.
-
서버
Callback URL 서버
하나의 주소로 오는 8종 요청을
type값으로 나눠 처리합니다. 그중 두 종류의 응답이 재생 허용 여부를 바꿉니다. -
오류
원인별 사용자 안내
오류 이름이 플랫폼마다 다르므로 같은 원인을 같은 문구로 묶는 대응표를 만들고 관리합니다.
-
업데이트
버전 추종
SDK는 고객사 앱에 포함되어 앱을 다시 배포해야 반영되고, PC 쪽은 최소 버전 값으로 사용자 업데이트를 유도합니다.
-
식별자
환경별 키 관리
App ID, 패키지 이름·Bundle ID, Authorization 문자열을 운영·테스트 환경별로 나눠 보관합니다.
연동 방식별 고객사 코드와 준비 조건
네 방식 모두 콘솔에서 만든 App의 ID로 DRM을 설정하고, 같은 Callback URL 규격으로 보고합니다.
| 방식 | 고객사 코드가 하는 일 | 준비 조건 |
|---|---|---|
| Agent | 설정 파일을 agent.js보다 먼저 불러온 뒤 playnplay.launch()에 실행 타입(재생·다운로드·커스텀 페이지)과 MediaItem, 창 크기를 넘깁니다. 여러 편 다운로드는 playnplay.download(), 접속 기기 정보는 getDeviceInfo()로 받습니다. | 사용자 PC에 PlaynPlay App 설치. CDNetworks 고객사는 전용 도메인 스크립트 사용 |
| 커스텀 페이지 | playnplay.startService()로 보안 서비스를 시작하고 video 요소의 open()으로 재생합니다. 거부 원인은 onSessionError로 받습니다. | 페이지와 같은 경로에 서비스 워커 스크립트. 기존 서비스 워커가 있으면 그 파일에 추가 |
| Android SDK | 앱 시작 때 startMediaPlayerService()에 App ID를 넣고, 미디어마다 withDrmConfiguration()을 붙여 presentMediaPlayer()로 엽니다. | aar와 Media3 등 의존성, 디슈가링과 Java 11, 매니페스트 권한·수신기·서비스 선언 |
| iOS SDK | AppDelegate에서 MediaPlaybackService.initialize(appId:)를 부르고, DrmConfiguration.Builder로 만든 설정을 붙여 present(mediaItems:startIndex:configuration:)로 엽니다. | NPlayerSDK 추가, Background Modes의 Audio, AirPlay, and Picture in Picture, 다운로드 시 백그라운드 세션 처리 |
Callback URL 서버 설계 포인트
서버가 늦거나 잘못 답하면 정상 사용자가 막힙니다. 문서에 정해진 규칙과 설계 권장을 칸을 나눠 적었습니다.
| 항목 | 문서에 정해진 규칙 | 설계 권장 |
|---|---|---|
| 요청 형식 | 콘솔에 등록한 주소로 JSON POST가 오고 type으로 종류를 구분합니다. | 수신 주소 하나에서 종류별 처리기로 분기 |
| 호출 인증 | Authorization은 선택 항목이며, 등록하면 Bearer 헤더로 실려 옵니다. | 등록하고 서버에서 검사, 교체 절차 마련 |
| 재생을 바꾸는 응답 | CheckAccessRights는 Ok·Expired·NoRights·DeviceLimitExceeded로 답하고 Ok일 때 expiresOn(Unix epoch time)을 보냅니다. NotifyPlaybackProgress는 Ok 또는 PlaybackLimitExceeded입니다. | 판정은 미리 계산해 둔 값으로 바로 응답하고 무거운 집계는 따로 실행 |
| 기록용 보고 | 상태·종료·다운로드·오프라인 로그·북마크 업데이트 보고에는 Ok로 답합니다. | sessionId 기준으로 같은 보고가 두 번 와도 한 번만 반영 |
| 보고 주기 | 진행 보고는 콘솔 Interval마다 옵니다. 2026년 8월 25일 SDK부터 진행 상태가 그대로면 생략됩니다. | 보고 공백을 이탈로 해석하지 않기 |
| 북마크 | useBookmarkCallback이 true면 GetBookmarks에 목록으로 응답하고 변경은 UpdateBookmarks로 받습니다. | 기존 북마크 테이블을 응답에 그대로 사용 |
| 식별값 | 8종 요청 모두에 userId와 userData가 들어 있습니다. | userData에 수강 신청·차시 ID |
평가 단계에서 열어 볼 원문
개발 공수는 데모보다 문서와 샘플이 더 정확히 알려 줍니다. 질문마다 확인할 원문 위치입니다.
| 질문 | 원문 위치 |
|---|---|
| 우리 앱의 최소 지원 버전과 맞나요? | Android 시작하기, iOS 시작하기 |
| 어떤 외부 라이브러리를 추가하나요? | Android 프로젝트 설정. SDK가 업데이트되면 의존성이 달라질 수 있다고 문서에 적혀 있습니다. |
| 지금 쓰는 Media3 플레이어를 살릴 수 있나요? | Android 사용 방법의 MediaPlayer(innerPlayer) |
| 플레이어 UI를 직접 만들 수 있나요? | Android MediaPlayerBaseView, iOS MediaPlayerBaseViewController |
| 거부 원인은 몇 가지로 오나요? | Android 예외 17종, iOS 오류 18종, PC 세션 오류 12종 |
| 샘플과 디버깅 도구가 있나요? | 데스크톱 샘플(서버 사이드 샘플 포함), 디버깅 툴, Android·iOS 문서 첫 화면의 샘플 다운로드 |
연동 기간의 작업 순서
문제가 생겼을 때 앱 쪽인지 서버 쪽인지 바로 가를 수 있도록 확인된 부분을 하나씩 늘려 가는 순서입니다.
-
식별자와 환경 분리
콘솔에 App을 만들고 운영·테스트 빌드의 패키지 이름·Bundle ID를 모두 등록합니다. 빠진 빌드는 앱 번들 미등록 오류로 재생이 거부됩니다.
-
샘플로 재생 확인
공개 샘플과 테스트 페이지로 DRM 파일 재생부터 확인해 두면, 이후 생기는 문제를 우리 코드 쪽으로 좁힐 수 있습니다.
-
권한 검사부터 구현
CheckAccessRights에 Ok와expiresOn을 돌려주는 최소 서버를 먼저 띄우고, 나머지 보고는 저장만 하는 단계로 시작합니다. -
채널별 연동과 오류 대응표
웹·Android·iOS의 오류 이름을 원인별로 묶습니다. 서버가
PlaybackLimitExceeded로 답한 경우는 세 채널 모두 같은 이름의 재생 제한 초과 오류로 처리됩니다. -
경계값·부하 시험
만료 직전과 직후, 기기 기준 경계, 보고 주기를 짧게 둔 동시 재생으로 서버 응답 시간과 판정을 확인합니다.
오픈 뒤 유지보수 업무
공개 변경 이력은 Android SDK, iOS SDK, PlaynPlay App, Callback URL 네 가지입니다. 배포 점검 목록에 넷을 함께 넣으세요.
-
의존성
빌드 설정 대조
2026년 1월 30일 Android SDK는
media3-datasource-okhttp의존성 추가를 요구했습니다. 올릴 때마다 프로젝트 설정 문서와 대조합니다. -
PC 앱
최소 버전 올리기
minVersion이상인 앱에는 업데이트 알림이 가지 않습니다. 1.0.32의 WebView2 대응처럼 재생 오류를 바로잡은 버전이 배포되면 이 값을 그 번호로 올릴지 판단합니다. -
OS 대응
OS 버전별 수정
iOS 18 탐색 버퍼링 수정(2026년 8월), Android 9.0 이하 재생 실패 수정(2026년 6월)처럼 특정 OS 문의와 연결되는 이력을 따로 표시해 둡니다.
-
서버
Callback 응답 지표
권한 검사는 라이선스 발급 과정에서 호출되므로 응답 시간과 실패 건수를 따로 지표로 둡니다.
-
규격
보고 방식 변경
북마크 업데이트 보고(2025년 2월), 진행 보고 생략(2026년 8월)처럼 서버 로직에 닿는 변경은 이력에서 먼저 찾아 대응합니다.
-
문의
기술 문의 창구
재현 절차와 플랫폼·SDK 날짜를 붙여 help@newin.co.kr로 보냅니다.
날짜별 변경 요약은 업데이트 기록에 있습니다.
설계 문서를 쓰기 전에 읽을 자료
개발 범위 산정과 서버 설계 리뷰에 바로 쓰는 페이지입니다.
가이드
가이드
가이드
가이드
가이드
역할
개발 리드 FAQ
-
웹과 앱의 Callback 서버를 따로 만들어야 하나요?
보고 규격은 Callback URL 문서 하나에 정의되어 있고, Android·iOS SDK 변경 이력에도 같은 날 같은 보고가 추가됐습니다. 한 서버에서 처리하고 채널 구분이 필요하면
userData에 채널 값을 넣으면 됩니다. -
iOS 시험에 실기기가 꼭 있어야 하나요?
Xcode의 Run destination에서 My Mac을 고르면 실제 iPhone·iPad 없이 테스트와 디버깅이 가능합니다. 문서 FAQ도 미디어가 재생되지 않을 때 이 설정부터 바꿔 보라고 안내합니다.
-
앱 화면 안에 플레이어를 넣고 아래에 목차를 두고 싶습니다.
Android는
MediaPlayerBaseFragment를 앱 화면에 올리고, iOS는MediaPlayerBaseViewController를 상속한 화면을 만듭니다. 기본 플레이어 화면을 그대로 쓸 때보다 직접 구현할 부분이 늘어나므로 일정에 반영하세요. -
커스텀 페이지의 새 창과 외부 링크는 어떻게 동작하나요?
PlaynPlay App 1.0.31부터
window.open은 앱 안 새 창으로 열리고, 외부 브라우저에서 열어야 하는 링크만 target 값을_external로 줍니다. 학습을 마치면playnplay.close()로 앱을 닫습니다.
PlaynPlay 도입을 위한
기술적 지원과 서비스를 제공합니다.
제품 문의부터 데모 시연까지, 모든 지원을 위해 세일즈 및 기술 지원 팀이 준비되어 있습니다.
-
제품 및 도입 문의
도입 범위, 일정, 견적을 상담합니다. 서비스 형태와 사용자 규모를 알려주시면 맞는 연동 방식과 보안 설정을 제안합니다.
-
Trial 신청
PlaynPlay의 기능을 먼저 테스트해 보세요. 트라이얼 기간 동안 귀사의 제품과 PlaynPlay를 연동하고 성능과 기능을 직접 검증할 수 있습니다.
-
PlaynPlay 기술 문의
SDK 연동, Callback URL 설계, DRM 패키징 중에 생기는 질문에 기술팀이 답합니다. 공개된 개발 문서와 샘플 프로젝트도 함께 확인하세요.