본문으로 건너뛰기

1. 다운로드 준비

SDK 초기화 및 인증, 저장소 권한 확인, 디바이스 가용 용량 체크 등 콘텐츠 다운로드를 위한 준비 단계에 대해 설명합니다.

이 문서의 모든 예제 코드는 공식 샘플 앱인 kollus_player_v2_android를 바탕으로 작성되었습니다.

KollusStorage 초기화​

샘플 애플리케이션은 내부 및 외부 저장소 관리를 위해 MultiKollusStorage 인스턴스를 만들고, SD 카드의 Mount/Unmount 상태 변화 이벤트에 대응합니다. 개발 프로젝트 연동 시에도 이와 동일한 구조적 패턴 구성을 권장합니다.

// BaseActivity.java

mMultiStorage = MultiKollusStorage.getInstance(getApplicationContext());

mMultiStorage.setCertification(
    KollusConstants.KEY,           // 카테노이드에서 발급받은 SDK 키
    KollusConstants.EXPIRE_DATE,   // 인증 만료일 설정 (예: "2050/12/31")
    isTablet);                     // 디바이스 유형 (true: 태블릿, false: 모바일)

int nRet = mMultiStorage.getErrorCode();
if (nRet != ErrorCodes.ERROR_OK) {
    // ERROR_INCORRECT_AUTH_KEY 등 오류 발생 시 키 만료 및 오입력 안내 후 프로세스 종료 처리
}

// 이벤트 감지를 위한 리스너 콜백 등록
mMultiStorage.registerKollusStorageListener(mKollusStorageListener);
mMultiStorage.registerKollusPlayerDRMListener(mKollusPlayerDRMListener);
mMultiStorage.registerSDStateChangeListener(mSDCardStateChangeListener);

setCertification 메서드가 호출되면 SDK에 의해 다음 작업이 순차적으로 실행됩니다.

  1. KollusStorage.initialize(key, expireDate, packageName) 호출을 통한 SDK 키 검증
  2. 등록된 개별 저장소 경로마다 storage.setDevice(path, isTablet) 연동을 통한 디바이스 바인딩

저장소 권한 및 용량 확인​

콘텐츠 다운로드 작업을 진행하기 위해 애플리케이션 사양 매니페스트 및 시스템 런타임 환경에 유효한 권한 명시와 남은 디스크 가용 용량 체크를 적용해야 합니다.

  • 외부 저장소 접근 권한: AndroidManifest.xml 내 READ_EXTERNAL_STORAGE 권한을 선언합니다. API 33 이상 환경의 경우 미디어별 상세 권한인 READ_MEDIA_VIDEO 등을 처리해야 합니다.
  • 포그라운드 서비스 권한: 앱 백그라운드 전환 상태에서도 다운로드 및 재생 상태를 유지하기 위한 포그라운드(Foreground) 제어 권한을 설정합니다.
  • 디바이스 가용 용량 확인: Utils.getAvailableMemorySize(path) 메서드를 호출하여 남은 디스크 용량을 확인합니다.
  • 다운로드 거절 임계값 설정: 샘플 앱 가이드 기준 MIN_FREE_SIZE = 150 MB 상수를 정의합니다. 콘텐츠 파일 크기 + 150MB보다 현재 디스크 여유 공간이 작으면 ERROR_STORAGE_FULL를 반환하고 작업을 거절합니다.
  • 다운로드 상태 유지 락 제어: 다운로드 중 절전 모드 및 Wi-Fi 연결 끊김 방지를 위해 PowerManager.WakeLock과 WifiManager.WifiLock를 사용합니다.

포그라운드 서비스 권한 설정​

1. 매니페스트 권한 선언​

포그라운드 서비스를 사용하려면 AndroidManifest.xml에 다음과 같이 권한을 선언해야 합니다.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
  • FOREGROUND_SERVICE_MEDIA_PLAYBACK: 재생 포그라운드 서비스 (MoviePlayerService 등)
  • FOREGROUND_SERVICE_DATA_SYNC: 다운로드 포그라운드 서비스 (DownloadService 등)

2. 다운로드 포그라운드 서비스 등록 패턴​

백그라운드 실행 제한 정책으로 인한 강제 종료를 방지하려면, 장시간 실행되는 작업은 반드시 Service(예: DownloadService) 내부에서 구현할 것을 권장합니다. Android 10(API 29) 이상 빌드 타겟인 경우 다운로드 컴포넌트 실행 패턴 구성 시 FOREGROUND_SERVICE_TYPE_DATA_SYNC 서비스 속성 정의가 의무화됩니다.

// DownloadService.java

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    startForeground(
        KollusConstants.SERVICE_DOWNLOAD,
        notificationBuilder.build(),
        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC);
} else {
    startForeground(KollusConstants.SERVICE_DOWNLOAD, notificationBuilder.build());
}

또한 동일하게 AndroidManifest.xml의 서비스 선언부에도 일치하는 타입을 함께 매칭해야 합니다.

<service
    android:name=".download.DownloadService"
    android:foregroundServiceType="dataSync" />

콘텐츠 다운로드 URL과 보안 주의사항​

다운로드 대상 URL은 일반적으로 https://v.kr.kollus.com/s?jwt=...와 같은 형태의 일회성(One-time) URL 구조를 가집니다.

  • 서버 간 연동 필수: JWT 발급 로직에는 보안 키가 포함되므로 반드시 고객사의 백엔드 서버에서 수행해야 합니다. 보안 취약점이 발생할 수 있으므로 모바일 앱 클라이언트가 JWT를 직접 생성해서는 안 됩니다.
  • SDK 처리 방식: 모바일 앱은 고객사 서버로부터 전달받은 URL을 변형 없이 그대로 SDK의 load(url, ...) 메서드에 전달하여 사용합니다.