다운로드·오프라인
내려받은 강의도
기한과 시청 기록은 서버가 관리합니다
학습자는 지하철이나 출장지에서 받아 둔 강의를 보고, 운영자는 볼 수 있는 기간과 시청 기록을 그대로 챙깁니다. PC와 Android·iOS의 다운로드 방식, 상태와 실패 이유가 운영에서 뜻하는 것, 오프라인 재생 기한, 오프라인 시청 기록 전송을 정리했습니다.
최종 수정
플랫폼별 다운로드 방식
PC는 웹 페이지가 PlaynPlay App에 내려받기를 맡기고, 모바일은 고객사 앱 안의 다운로드 매니저가 받습니다.
| 항목 | PC (Agent) | Android SDK | iOS SDK |
|---|---|---|---|
| 시작 방법 | launch()의 Downloading 타입, 또는 download() |
DownloadManager.shared.add() |
DownloadManager.shared.add(mediaItem:) |
| 여러 편 받기 | download()에 MediaItem 배열을 한 번에 전달 | 항목마다 add, 동시 진행 수는 maxParallelDownloads(기본 3) | 항목마다 add, 동시 진행 수는 maxParallelDownloads(기본 3) |
| 저장 위치 | Metadata의 downloadPath로 경로 표시 값 지정 | 최상위 폴더 downloadsUri, 항목별 displayPath·toUri | 최상위 폴더 downloadsUrl, 항목별 displayPath·toUrl |
| 사전 설정 | 웹 페이지에 설정 파일과 agent.js | AndroidManifest에 다운로드 완료 수신기 선언 | AppDelegate에 백그라운드 URL 세션 처리 연결 |
다운로드 매니저는 iOS SDK에 2024년 3월 13일, Android SDK에 3월 14일 추가됐고, 오프라인 재생은 두 SDK 모두 2024년 4월 17일부터입니다. 2026년 7월 2일 배포본부터는 영상을 받을 때 자막도 함께 저장됩니다.
다운로드함을 그리는 다섯 가지 상태
Android·iOS SDK의 상태 값은 같습니다. 앱은 상태가 바뀔 때 onStatusChanged, 진행될 때 onProgressUpdated를 받아 화면을 갱신합니다.
| 상태 | 문서의 뜻 | 다운로드함에서 할 일 (권장) |
|---|---|---|
| Pending | 다운로드할 수 있거나 차례를 기다리는 상태 | 대기 중으로 표시합니다. 동시 진행 수를 넘겨 추가한 항목은 바로 시작하지 않으니 순서를 보여 주면 문의가 줄어듭니다. |
| Downloading | 다운로드 중 | 받은 크기와 전체 크기로 진행률 막대를 그립니다. |
| Paused | 일시 정지 | 재개 버튼을 둡니다. 전체 재개는 resumeAll()입니다. |
| Completed | 다운로드 완료 | 재생 버튼과 함께 남은 시청 기간을 보여 줍니다. |
| Failed | 다운로드 실패 | 실패 이유에 맞는 안내 문구를 띄웁니다. |
Android는 진행 정보를 받은 크기(downloadedSize)와 전체 크기(fileSize)로 주며 단위는 바이트입니다. iOS는 받은 크기와 전체 크기를 한 쌍의 값으로 줍니다. 서버로 가는 다운로드 상태 보고는 이와 별개의 값(Started, Completed, Canceled, Failed)을 씁니다.
실패 이유와 고객센터 대응
Android SDK는 실패 이유를 13가지 값으로 구분합니다. 누가 해결할 문제인지로 묶어 두면 상담 응대가 빨라집니다. iOS SDK의 failedReason은 문자열로 제공됩니다.
| 묶음 | 실패 이유 (Android) | 운영상 의미 | 대응 (권장) |
|---|---|---|---|
| 수강 권한 | NoAccessRights, AccessRightsExpired, Unauthorized | 접근 권한 없음, 만료, 권한 없음 | 수강 상태를 확인하고 연장이나 재신청을 안내합니다. |
| 기기 정책 | DeviceLimitExceeded | 기기 제한 초과 | 콘솔 디바이스 관리에서 기기 기록을 확인하고 필요하면 리셋합니다. |
| 학습자 저장소 | InsufficientSpace, DeviceNotFound, FileError, FileAlreadyExists | 공간 부족, SD 카드 없음, 저장소 문제, 같은 파일 있음 | 공간 확보나 저장소 변경을 안내하고, 같은 파일이면 목록에서 지운 뒤 다시 받게 합니다. |
| 네트워크·서버 | HttpDataError, TooManyRedirects, UnhandledHttpCode, CannotResume | HTTP 오류, 리다이렉션 과다, 처리할 수 없는 HTTP 코드, 재개 불가 | 미디어 서버 담당에게 넘깁니다. 재개 불가는 지우고 새로 받게 합니다. |
| 기타 | Unknown | 알 수 없는 이유 | 앱 버전과 기기 모델을 함께 모아 문의합니다. |
2024년 4월 Android SDK부터 만료된 콘텐츠를 받으려 하면 실패 사유가 Failed (Unauthorized)로 표시됩니다. 원인별 상담 문구는 고객지원 플레이북에 정리했습니다.
오프라인 재생 기한
내려받은 파일을 네트워크 없이 볼 수 있는 기간입니다. 재생이나 다운로드를 요청할 때 넘기는 DRM 설정에 넣으므로 과정별로 다르게 줄 수 있습니다.
| 설정 | 동작 | 맞는 과정 (권장) |
|---|---|---|
| 비움 (null) | 기한 없이 재생 | 기간 제한이 없는 사내 공개 교육 |
| 0 | 오프라인 재생 권한 없음 | 대외비 교육, 맛보기 강의 |
| n | n초까지 재생 | 기간제 수강. 남은 수강 기간을 넘지 않게 계산해 넣습니다. |
PC는 DRM 설정의 offlineAccessPeriod(초), Android는 withDrmConfiguration()의 offlineAccessPeriod(java.time.Duration), iOS는 DrmConfiguration.Builder의 offlineAccessPeriod(_)로 넣습니다. 앱이 받는 오류는 오프라인 접근 권한 없음(NoOfflineAccessRights)과 오프라인 접근 권한 만료(OfflineAccessRightsExpired)로 나뉩니다. Android SDK는 2026년 3월 30일 이 값이 null일 때의 오동작을 고쳤습니다.
오프라인 시청 기록 전송
연결이 끊긴 동안의 재생 기록은 기기에 남았다가 다시 온라인이 되면 NotifyOfflinePlaybackLog로 서버에 도착합니다. 재생 시작과 종료 시점의 연결 상태에 따라 대상이 정해집니다.
| 재생 시작 | 재생 종료 | 오프라인 기록 전송 | 서버 처리 (권장) |
|---|---|---|---|
| 오프라인 | 오프라인 | 대상 | 세션 전체가 나중에 한 번에 들어옵니다. 시작 시간 기준으로 학습일을 잡습니다. |
| 오프라인 | 온라인 | 대상 | 시청 중 연결이 돌아온 경우입니다. 같은 시간대의 다른 보고와 겹치는지 확인합니다. |
| 온라인 | 오프라인 | 대상 | 시청 중 연결이 끊긴 경우입니다. 앞서 받은 진행 보고와 sessionId로 맞춰 두 번 더하지 않습니다. |
| 온라인 | 온라인 | 대상 아님 | 평소의 진행·종료 보고로 처리합니다. |
한 번의 전송에 세션 목록이 담기고, 세션마다 시작과 종료 시각, 재생 위치, 재생 시간과 시청 시간, 종료 원인이 들어 있습니다. Android·iOS SDK는 2025년 6월 24일, PlaynPlay App은 1.0.26(2025년 7월 21일)부터 보내며, 2026년 3월 17일 두 SDK의 오프라인 재생 콜백 오류가 고쳐졌습니다. 오프라인 학습 운영 전체는 오프라인 학습 가이드에서 다룹니다.
모바일 데이터와 저장 공간
앱 다운로드에서 문의가 몰리는 부분입니다. 출시 전에 정하고 시험할 항목을 모았습니다.
-
Cellular
항목별 Wi-Fi 전용
add()의 allowsCellularAccess는 항목마다 넘기는 값이고 기본값은 true입니다. 용량이 큰 강의만 false로 넘겨 Wi-Fi에서 받게 묶을 수 있습니다.
-
No Wi-Fi
Wi-Fi가 끊겼을 때
셀룰러 사용을 막은 상태에서 Wi-Fi 없이 재생하려 하면 Android는 NoCellularAccessException, iOS는 noCellularAccess 오류를 받습니다. 안내 문구에 설정 변경 방법을 넣어 두세요.
-
Size
용량 미리 알리기
받기 시작하면 전체 크기를 알 수 있지만, 학습자는 누르기 전에 용량을 보고 싶어 합니다. 강의 정보에 파일 크기를 함께 관리해 다운로드 버튼 옆에 적어 두기를 권합니다.
-
Cleanup
목록 정리
remove()는 한 항목, removeCompleted()는 완료 항목 전체를 목록에서 지웁니다. 목록에서 지운 뒤 기기 저장 공간이 실제로 회수되는지 출시 전에 확인하세요.
-
Background
앱을 내려도 계속 받기
iOS는 AppDelegate의 백그라운드 URL 세션 처리를 연결해야 앱이 백그라운드로 가도 내려받기가 이어집니다. Android는 2025년 6월 백그라운드 다운로드 문제를 두 차례 고쳤습니다.
-
Protection
받은 파일 보호
2026년 2월 2일 두 SDK가 다운로드 파일의 DRM 키 저장 방식을 개선했고, Android는 6월에 오프라인 재생 중 녹화 차단 문제를 고쳤습니다. 보안 점검은 최신 SDK로 합니다.
다운로드 운영 FAQ
-
수강 기간과 오프라인 기한은 어떻게 맞추나요?
두 값은 설정 위치가 다릅니다. 앱은 PlaynPlay 재생 정보 저장소에서 미디어의 만료 일시(expiresOn)를 읽을 수 있고, 오프라인 기한은 다운로드를 요청할 때 DRM 설정에 넣는 값입니다. 남은 수강 기간보다 짧은 값을 넘기기를 권하며, 기한을 세기 시작하는 시점은 첫 시험에서 확인하세요.
-
누가 어떤 영상을 받았는지 서버에서 알 수 있나요?
다운로드 상태 보고가 시작, 완료, 취소, 실패 때마다 사용자 ID, 미디어 URL, 생성 시각과 함께 옵니다. Android·iOS SDK에는 2024년 5월 20일 추가됐습니다. 다운로드 콘텐츠의 접근 권한 검사는 offline 값이 true로 오므로 다운로드 허용 여부를 서버가 따로 판정할 수도 있습니다.
-
PC에서 받은 파일은 어디에 보이나요?
Metadata의 downloadPath에 넣은 경로 표시 값이 쓰입니다. 강좌명과 차시 번호를 넣는 규칙을 정해 두면 학습자가 받은 파일을 찾기 쉽습니다.
-
동시에 몇 개까지 받나요?
Android·iOS 모두 maxParallelDownloads 기본값이 3이고 앱에서 바꿀 수 있습니다. 한 차시 전체를 한꺼번에 담게 하는 앱이라면 기기 성능과 네트워크를 보고 값을 정하세요.
함께 보면 좋은 페이지
-
가이드
오프라인 학습 운영
다운로드 학습을 열 때 기한·네트워크·기록 규칙을 정합니다
오프라인 학습 운영 자세히 보기 -
기능
DRM·라이선스
라이선스를 내주는 순간 고객사 서버가 재생 여부를 답합니다
DRM·라이선스 자세히 보기 -
가이드
오류 대응 가이드
오류 이름으로 원인과 처리 담당을 가립니다
오류 대응 가이드 자세히 보기
PlaynPlay 도입을 위한
기술적 지원과 서비스를 제공합니다.
제품 문의부터 데모 시연까지, 모든 지원을 위해 세일즈 및 기술 지원 팀이 준비되어 있습니다.
-
제품 및 도입 문의
도입 범위, 일정, 견적을 상담합니다. 서비스 형태와 사용자 규모를 알려주시면 맞는 연동 방식과 보안 설정을 제안합니다.
-
Trial 신청
PlaynPlay의 기능을 먼저 테스트해 보세요. 트라이얼 기간 동안 귀사의 제품과 PlaynPlay를 연동하고 성능과 기능을 직접 검증할 수 있습니다.
-
PlaynPlay 기술 문의
SDK 연동, Callback URL 설계, DRM 패키징 중에 생기는 질문에 기술팀이 답합니다. 공개된 개발 문서와 샘플 프로젝트도 함께 확인하세요.