PlaynPlay
PlaynPlay

오류 대응 가이드

오류 이름으로
원인과 처리 담당을 가립니다

Android SDK 예외 17종, iOS SDK 오류 18종, PC 커스텀 페이지 세션 오류 12종, Android 다운로드 실패 사유 13종을 운영자와 CS가 쓰는 표로 묶었습니다. 오류 이름과 문서상 의미는 개발 문서 그대로 옮겼고, 원인과 처리 담당 칸은 운영 권장안입니다.

최종 수정

오류 대응을 표현한 PlaynPlay 일러스트
Delivery

오류가 학습자 화면에 닿는 경로

원인이 같아도 플랫폼마다 오류를 받는 자리가 다릅니다. 안내 문구는 그 자리에서 띄웁니다.

  • Android SDK

    예외 클래스로 구분

    앱은 onError 리스너나 Error 핸들러로 PlaybackException을 받습니다. 어떤 오류인지는 MediaPlayerException을 상속한 예외 클래스 이름이 알려 주고, 마지막으로 난 오류는 MediaPlayer.error에서 다시 읽습니다.

  • iOS SDK

    열거형 케이스로 구분

    onError(error:)나 error 핸들러로 받고 MediaPlayerError로 원인을 가립니다. present()를 그대로 쓰면 오류 설명과 Close 버튼만 있는 알림이 뜨고, Close를 누르면 재생 화면이 닫힙니다.

  • PC

    커스텀 페이지 세션 오류

    video 요소의 onSessionError로 type과 message를 받습니다. 어떤 문구를 어디에 띄울지는 고객사 페이지가 정합니다.

  • Server

    서버에는 종료 원인까지만

    재생 종료 보고와 오프라인 로그는 종료 원인 Error를, 다운로드 상태 보고는 Failed를 알려 줍니다. 구체적인 오류 이름은 앱 쪽 기록으로 확인합니다.

2026년 1월 30일 Android·iOS SDK에서 오류 메시지 출력이 개선됐습니다. 오류 이름과 message를 앱 로그와 문의 양식에 남기세요. 등록되지 않은 앱 오류와 셀룰러 차단 오류는 message 매개변수 없이 정의돼 있으니 문구를 앱에서 준비합니다.

Rights & Policy

권한·정책 오류

고객사 서버 응답이나 계정 정책에서 생기는 오류입니다. 대부분 CS 확인과 안내로 끝납니다.

오류 학습자가 겪는 상황 가능성 높은 원인 처리 담당
접근 권한 만료: AccessRightsExpired(Exception), accessRightsExpired 접근 권한이 만료돼 열리지 않음 접근 권한 검사에 Expired 응답. 수강·대여 기간 종료 CS: 기간 확인 후 연장·재구매 안내
접근 권한 없음: NoAccessRights(Exception), noAccessRights 접근 권한이 없어 열리지 않음 NoRights 응답. 미신청, 환불, 휴면, 또는 판정 오류 CS. 판정이 틀렸으면 고객사 서버
기기 제한 초과: DeviceLimitExceeded(Exception), deviceLimitExceeded 허용 기기 수를 넘겨 막힘 새 기기로 교체, 가족·지인과 계정 공유 CS: 콘솔 디바이스 관리 확인과 리셋
동시 접속: MultipleConnections(Exception), multipleConnections 동시 접속이 감지됨 다른 기기나 창에서 같은 계정 재생 CS: 동시 접속 관리·세션 관리 확인
재생 제한 초과: PlaybackLimitExceeded(Exception), playbackLimitExceeded 재생 도중 재생 제한 초과 오류로 처리됨 고객사 서버가 진행 보고에 재생 제한 초과로 답함(배수·횟수 기준) 고객사 서버 기준 확인 후 CS 안내
권한 없음: Unauthorized(Exception), unauthorized 권한이 없다는 오류 연동 설정 불일치, 만료 콘텐츠 다운로드 고객사 개발, 이어서 Newin

이 표의 PC 세션 오류 이름은 Android 이름에서 Exception을 뺀 것과 같습니다. Android는 2024년 4월 8일부터 만료 콘텐츠 다운로드 실패를 'Failed (Unauthorized)'로 표시합니다. 응답 설계는 접근 권한 서버 설계에 있습니다.

License · Session · Device

라이선스·세션·환경 오류

연동 설정, 네트워크, 기기 상태에서 생기는 오류입니다. 반복되거나 몰리면 개발과 Newin으로 넘깁니다.

오류 학습자가 겪는 상황 가능성 높은 원인 처리 담당
라이선스 없음: LicenseNotFound(Exception), licenseNotFound 라이선스를 찾지 못해 열리지 않음 패키징 파일과 App 설정 불일치, 잘못된 미디어 URL 고객사 개발, 이어서 Newin
라이선스 확인 실패: LicenseCheckFailed(Exception), LicenseCheckFailureException, licenseCheckFailed 라이선스 확인 실패 권한 검사 응답 지연·형식 오류, 인증 서버 문제 고객사 서버, 이어서 Newin
iOS noLicenseData, PC LicenseServerConnectionFailed 라이선스 데이터 없음, 라이선스 서버 연결 실패 사내망·보안 프로그램이 라이선스 통신을 막음, 구버전 앱 CS: 네트워크·버전 확인 뒤 Newin
세션 없음·종료: SessionNotFound, SessionClosed 계열 세션을 찾지 못하거나 세션이 끝남 끝난 세션으로 재생을 이어감 CS: 플레이어를 다시 열도록 안내. 반복되면 Newin
네트워크: NetworkException, network 네트워크 오류 회선 불안정, 방화벽 CS
셀룰러 차단: NoCellularAccessException, noCellularAccess 셀룰러를 막은 상태에서 Wi-Fi가 끊긴 채 재생 시도 앱의 셀룰러 비허용 설정 CS: Wi-Fi 연결 안내
미등록 앱: AppBundleNotRegisteredException, appBundleNotRegistered 콘솔에 없는 앱 식별자로 실행됨 출시 빌드의 패키지 이름·Bundle ID 미등록 고객사 개발
iOS screenCaptureDetected 화면 캡처가 감지됨 화면 녹화·캡처 실행 CS: 녹화 종료 안내
미정의: UnexpectedException, unexpected, Unexpected 정의되지 않은 오류 분류 밖의 문제 Newin. Android는 cause까지 전달

표기 방식은 위 표와 같습니다. Android의 두 라이선스 확인 실패 예외는 문서 설명이 똑같으니 학습자 문구 하나로 처리해도 됩니다. PC 사용자의 연결 실패 문의가 늘면 앱 버전부터 보세요. 2025년 12월 9일 배포된 1.0.32가 WebView2 143.0.3650.66 환경의 재생 문제를 고친 버전입니다.

Offline & Download

오프라인·다운로드 오류

오프라인 오류는 Android·iOS SDK에 있고, 다운로드 실패 사유 13종은 Android 문서에 있습니다. iOS 다운로드 항목은 실패 사유를 문자열로 줍니다.

오류·사유 학습자가 겪는 상황 가능성 높은 원인 처리 담당
NoOfflineAccessRights(Exception), noOfflineAccessRights 받은 강의를 오프라인으로 열 수 없음 오프라인 재생 기한 0 CS: 온라인 재생 안내
OfflineAccessRightsExpired(Exception), offlineAccessRightsExpired 받은 강의가 기한 경과로 오프라인에서 안 열림 오프라인 재생 기한 경과 CS: 온라인 재생 안내
권한: AccessRightsExpired, NoAccessRights, DeviceLimitExceeded, Unauthorized 다운로드 실패 접근 권한 검사 거절, 만료 콘텐츠 CS, 판정 오류면 고객사 서버
저장소: InsufficientSpace, DeviceNotFound, FileError, FileAlreadyExists 다운로드 실패 기기 용량 부족, 외부 저장소(SD 카드) 빠짐, 저장소 오류, 같은 이름 파일 CS: 용량 정리와 저장 위치 점검 안내
전송: HttpDataError, TooManyRedirects, UnhandledHttpCode, CannotResume 다운로드 실패, 이어받기 불가 미디어 서버·CDN 응답 문제 고객사 개발, 이어서 Newin
Unknown, iOS 실패 사유 문자열 다운로드 실패 분류되지 않은 원인 문자열 그대로 Newin에 전달

서버에서 다운로드 상태 보고의 Failed 건수를 강의별로 세어 보면 문제 파일을 빨리 찾습니다. 기한 설계는 오프라인 학습 운영을 보세요.

Owners

처리 담당별 넘기는 기준

표의 담당 칸을 세 갈래로 묶었습니다. 넘길 때 함께 보낼 정보까지 정해 두면 되묻는 시간이 줄어듭니다.

  • 1st Line

    CS

    권한·기기·동시 접속·네트워크·저장 공간·오프라인 기한 오류를 맡습니다. 콘솔 디바이스 관리, 동시 접속 관리, 세션 관리로 확인하고 정해 둔 답변으로 마무리합니다.

  • Customer

    고객사 서버·개발

    판정이 틀린 권한 오류, 재생 제한 기준, 앱 등록 누락, 미디어 서버 전송 오류, SDK와 앱 업데이트를 맡습니다.

  • Newin

    Newin 기술 지원

    라이선스·세션 오류 반복, 정의되지 않은 오류, 최신 버전에서도 남는 문제를 help@newin.co.kr에 접수합니다. 접수할 때 오류 이름·message, 플랫폼·버전, 사용자 ID, 발생 시각, 미디어 URL을 함께 적습니다.

Message Design

안내 문구를 준비하는 순서

오류 이름은 개발자용입니다. 출시 전에 학습자용 문구와 다음 행동으로 바꿔 둡니다.

  1. 표 복사

    이 페이지의 표에 서비스 문구 칸을 더해 플랫폼별 이름을 한 행으로 관리합니다.

  2. 행동 하나 붙이기

    문구마다 학습자가 할 일 하나를 적습니다. Wi-Fi 연결, 다른 기기 재생 종료, 저장 공간 확보, 고객센터 문의처럼 바로 할 수 있는 행동이어야 합니다.

  3. 원문 보존

    화면에는 서비스 문구를, 앱 로그와 문의 양식에는 오류 이름과 message 원문을 남깁니다.

  4. 재현과 버전 점검

    서버 응답 변경, 네트워크 차단, 셀룰러 비허용, 미등록 빌드로 오류를 일부러 내 봅니다. 업데이트 때는 변경 이력의 오류 관련 수정을 확인합니다.

Get Started

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

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

  • 제품 및 도입 문의

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

  • Trial 신청

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

  • PlaynPlay 기술 문의

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