구현 가이드
Android 환경에서 Kollus SDK를 사용하여 DRM 콘텐츠를 디바이스에 다운로드하고, 네트워크 연결이 없는 환경에서도 안전하게 재생하기까지의 전체 프로세스를 다룹니다.
이 문서의 모든 예제 코드는 공식 샘플 앱인 kollus_player_v2_android를 바탕으로 작성되었습니다.
사전 확인 사항: SDK 키와 인증
Kollus SDK는 카테노이드에서 발급하는 SDK 키(Key)와 만료일 정보를 기반으로 인증을 수행합니다.
올바른 키를 발급받지 못했거나 유효 기간이 만료된 키를 사용하는 경우, 다운로드 및 오프라인 재생 관련 API 호출 시 ERROR_INCORRECT_AUTH_KEY 에러가 발생하며 동작이 실패합니다.
| 항목 | 설명 및 위치 |
|---|---|
| SDK 키 | 기술 지원팀 또는 영업 담당자(AM)를 통해 발급받은 고유 키 |
| 만료일 | SDK 키와 함께 제공되는 인증 유효 기간 (예: 2050/12/31) |
| 패키지 식별자 | context.getPackageName(): SDK 내부에서 자동으로 식별 및 인증에 사용 |
SDK 키 발급
SDK 키는 콘솔에서 직접 발급할 수 없습니다. 기술 지원팀(tech_support@kollus.com)으로 패키지명/Bundle ID와 함께 발급을 요청하세요.
콘텐츠 다운로드 URL과 보안 주의사항
다운로드 대상 URL은 일반적으로 https://v.kr.kollus.com/s?jwt=...와 같은 형태의 일회성(One-time) URL 구조를 가집니다.
- 서버 간 연동 필수: JWT 발급 로직에는 보안 키가 포함되므로 반드시 고객사의 백엔드 서버에서 수행해야 합니다. 보안 취약점이 발생할 수 있으므로 모바일 앱 클라이언트가 JWT를 직접 생성해서는 안 됩니다.
- SDK 처리 방식: 모바일 앱은 고객사 서버로부터 전달받은 URL을 변형 없이 그대로 SDK의
load(url, ...)메서드에 전달하여 사용합니다.
구현 가이드 구성
- 1. 다운로드 준비: SDK 초기화 및 인증, 저장소 권한 확인, 디바이스 가용 용량 체크
- 2. 스트리밍 재생: JWT URL 온라인 재생, 미디어 전달 방식 특징, 백그라운드 재생 제어
- 3. 콘텐츠 다운로드: 정보 등록 및 다운로드 시작 2단계 제어, 취소/재시작 프로세스
- 4. 다운로드 목록 관리: 다운로드 콘텐츠 목록 조회, 상태별 플래그 분기, 앱 재시작 후 복원
- 5. 오프라인 재생: 로컬 파일 재생 흐름, 네트워크 단절 시 DRM 검증 조건 처리
- 6. DRM 라이선스 갱신: 라이선스 만료 조건 확인, 일괄 갱신 처리
- 7. 다운로드 콘텐츠 삭제: 단일/전체 콘텐츠 삭제 및 DRM 응답에 따른 만료 파일 정리
- 8. 다운로드 이벤트/콜백: 다운로드 상태 변경 추적 및 DRM 검증/갱신 결과를 다루는 리스너
- 9. 다운로드 에러 코드: 주요 에러 대응 방법
- 안티패턴 (자주 하는 실수): 잘못된 구현 사례와 이를 올바르게 해결하는 방법
참고 자료
- 공식 샘플 앱:
kollus_player_v2_android - 콜백 상세 명세: DRM 다운로드 콜백
- 기술 문의: tech_support@kollus.com