개발 가이드

이 문서는 Android SDK를 활용한 앱 개발 지침을 제공합니다. SDK는 콘텐츠 재생 및 관리를 위한 핵심 API를 제공하며, 플레이어 UI는 개발자가 직접 구현해야 합니다.

---

Android SDK API 레퍼런스

SDK에 포함된 전체 API 명세는 아래 문서를 참고하세요.

• Android SDK - API 레퍼런스

---

지원 아키텍처 및 라이브러리 구성

SDK는 다양한 디바이스 환경과의 호환성을 보장하기 위해 다음 CPU 아키텍처용 Native 라이브러리와 Java 라이브러리를 포함합니다.

• 지원 아키텍처: arm64-v8a, armeabi, armeabi-v7a, x86, x86_64
• 라이브러리
  • kollusplayer_sdk-debug.jar: 개발 단계에서 사용하며 디버그 로그를 포함합니다.
  • kollusplayer_sdk-release.jar: 실제 마켓 배포용이며 로그를 포함하지 않습니다.

---

KollusStorage

KollusStorage는 SDK의 핵심 요소로, 다음과 같은 주요 기능의 라이프사이클 관리 및 데이터 처리를 담당합니다.

• SDK 인증
• 콘텐츠 정보 조회
• 콘텐츠 다운로드 및 삭제
• 스트리밍 캐시 데이터 관리

인스턴스 초기화 및 해제 절차

1. 인스턴스 획득 (getInstance)

KollusStorage는 하나의 스토리지에 대해 단일 인스턴스(Singleton)로 운영되어야 합니다.
공통 BaseActivity에서 초기화한 후, 하위의 모든 Activity가 동일한 인스턴스를 공유하도록 설계하는 것을 권장합니다.

2. SDK 인증 (initialize)

발급받은 키를 사용하여 SDK 사용의 유효성을 검증합니다.

public int initialize(String key, String expireDate, String packageName);

• 반환 코드
  • ErrorCodes.ERROR_OK: 정상
  • ErrorCodes.ERROR_INVALID_KEY: 잘못된 키
  • ErrorCodes.ERROR_EXPIRED_KEY: 키 만료

3. 경로 및 디바이스 설정 (setDevice/setDeviceAsync)

데이터가 저장될 스토리지 경로와 디바이스 고유 식별자를 설정합니다.
비동기 방식인 setDeviceAsync보다 안정성이 높은 동기 방식인 setDevice 사용을 강력히 권장합니다. (동기 방식 처리 시 평균 소요 시간: 약 100ms)

동기 방식 (권장)

public int setDevice(String storagePath, String deviceSha1, String deviceGUIDMd5, boolean bTablet); 

비동기 방식

public void setDeviceASync(String storagePath, String deviceSha1, String deviceGUIDMd5, boolean bTablet, OnKollusStorageDeviceListener listener); 

4. 자원 해제 및 재설정 (finish)

사용 중인 리소스를 정리하거나 스토리지 경로를 변경해야 할 때 이 메서드를 호출합니다.
finish()를 호출한 후 다시 스토리지를 사용하려면 반드시 위의 1~3번 과정을 다시 수행해야 합니다.

---

콘텐츠 다운로드 구현

다운로드 목록 조회

현재 디바이스에 다운로드된 콘텐츠 목록을 가져옵니다.

ArrayList<KollusContent> contentsList = kollusStorage.getDownloadContentList(); 

다운로드 실행

다운로드 프로세스를 제어하려면 OnKollusStorageListener를 등록하여 이벤트(진행률, 완료, 오류 등)를 수신해야 합니다. 이벤트 수신이 더 이상 필요하지 않은 경우 unregisterOnKollusStorageListener를 호출하여 리스너를 해제하세요.

이벤트 리스너 인터페이스

public interface OnKollusStorageListener {
    /** Called when the download is complete */
    void onComplete(int index);

    /** Called when the download progress is updated */
    void onProgress(int index, int percent);

    /** Called when an error occurs during the process */
    void onError(int index, int errorCode);
}

1. 다운로드 준비 (load)

다운로드할 콘텐츠의 정보를 로드하고 준비 작업을 수행합니다.

• 주의: load 메서드는 동시 호출을 지원하지 않습니다. 한 콘텐츠의 로드 작업이 완료된 후 다음 콘텐츠를 호출해야 합니다.
• 예외 처리: 음수 값이 반환되면 오류 상태이므로 ErrorCodes를 참조하여 예외 처리를 수행하세요.

public int load(String path, String extraDrmParam, KollusContent content);

파라미터	타입	설명
path	String	다운로드할 콘텐츠의 소스 경로
extraDrmParam	String	DRM 다운로드 콜백 시 전달할 추가 파라미터 (기본값: null)

2. 다운로드 시작 (download)

준비된 콘텐츠의 실제 데이터 전송을 시작합니다.

• 저장 공간 검증: 다운로드 전 content.getFileSize()를 호출하여 콘텐츠 파일의 크기를 확인하세요. 디바이스의 남은 저장 공간이 파일 크기 + 150MB보다 커야 안정적인 작업이 가능합니다.
• 예외 처리: 음수 값이 반환되면 오류 상태이므로 ErrorCodes를 참조하여 예외 처리를 수행하세요.

public int download(String mediaContentKey);

파라미터	타입	설명
mediaContentKey	String	다운로드할 콘텐츠의 미디어 콘텐츠 키

다운로드 취소

현재 진행 중인 다운로드 작업을 중단하고 해당 세션을 종료합니다.

public int unload(String mediaContentKey);

파라미터	타입	설명
mediaContentKey	String	다운로드를 취소할 콘텐츠의 미디어 콘텐츠 키

다운로드 콘텐츠 삭제

디바이스의 스토리지에 저장된 다운로드 완료 파일을 삭제합니다.

public int remove(String mediaContentKey);

파라미터	타입	설명
mediaContentKey	String	삭제할 콘텐츠의 미디어 콘텐츠 키

---

콘텐츠 재생 구현

1. MediaPlayer 인스턴스 생성

콘텐츠를 재생할 MediaPlayer 객체를 생성합니다.

public MediaPlayer(Context context, KollusStorage storage, int port);

2. 이벤트 리스너 등록

플레이어의 상태 변화 및 예외 상황을 감지하기 위해 아래의 리스너들을 구현하고 등록해야 합니다.

필수 구현 리스너

• OnPreparedListener: 재생 준비 완료 상태 감지
• OnCompletionListener: 재생 완료 시점 감지
• OnErrorListener: 재생 중 발생하는 예외 상황 처리
• OnVideoSizeChangedListener: 해상도 정보 획득 및 변경 감지

전체 이벤트 리스너

재생

• 재생 준비 완료: setOnPreparedListener(OnPreparedListener listener);

  public interface OnPreparedListener{
      void onPrepared(MediaPlayer mp);
  }

• 재생 완료: setOnCompletionListener(OnCompletionListener listener);

  public interface OnCompletionListener{
      void onCompletion(MediaPlayer mp);
  }

• 재생 중 오류 발생: setOnErrorListener(OnErrorListener listener);

  public interface OnErrorListener{
      boolean onError(MediaPlayer mp, int what, int extra);
  }

• 재생 정보 알림: setOnInfoListener(OnInfoListener listener);

  public interface OnInfoListener{
      boolean onInfo(MediaPlayer mp, int what, int extra); 
      void onBufferingStart(MediaPlayer mp);
      void onBufferingEnd(MediaPlayer mp); 
      void onFrameDrop(MediaPlayer mp);
      void onDownloadRate(MediaPlayer mp, int downloadRate);
      void onDetectBandwidthList(MediaPlayer mp, List list); 
      void onChangedBandwidth(MediaPlayer mp, BandwidthItem item);
  }

---

보안

• DRM(Widevine 등) 오류: void setOnCencDrmListener(OnCencDrmListener listener);

  public interface OnCencDrmListener{
      void onProxyError(int nErrorCode, String strErrorMessage);
  }

• 에뮬레이터 재생 시도 감지: setEmulatorCheckerListener(EmulatorCheckerListener listener);

  public interface EmulatorCheckerListener {
      public void onRunningEmulator();
  }

• 외부 디스플레이 연결 감지: setOnExternalDisplayDetectListener(OnExternalDisplayDetectListener listener);

  public interface OnExternalDisplayDetectListener{
      public void onExternalDisplayDetect(int type, boolean plugged);
  }

---

콘텐츠 및 부가 기능

• 콘텐츠 해상도 변경: setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener);

  public interface OnVideoSizeChangedListener{
      public void onVideoSizeChanged(MediaPlayer mp, int width, int height);
  }

  • 참고: 해당 리스너는 재생 시작 시 최초 해상도 정보를 전달받을 때에도 호출됩니다.

• 자막 노출: setOnTimedTextListener(OnTimedTextListener listener);

  public interface OnTimedTextListener{
      public void onTimedText(MediaPlayer mp, String text);
      public void onTimedImage(MediaPlayer mp, byte[] image, int width, int height);
  }

• LMS 전송 확인

  • registerKollusPlayerLMSListener(KollusPlayerLMSListener listener);
  • unregisterKollusPlayerLMSListener(KollusPlayerLMSListener listener);

  public interface KollusPlayerLMSListener {
      /**
       * Delivers relevant data when progress rate data is sent to the server.
       * @param request Message sent to the server
       * @param response Message received from the server as a response
       */
      void onLMS(String request, String response);
  }

---

사용자 인터랙션

• 탐색(Seek) 완료: setOnSeekCompleteListener(OnSeekCompleteListener listener);

  public interface OnSeekCompleteListener{
      public void onSeekComplete(MediaPlayer mp);
  }

• 북마크:setKollusPlayerBookmarkListener(KollusPlayerBookmarkListener listener);

  public interface KollusPlayerBookmarkListener {
      /**
       * Triggered when official bookmarks or "My Bookmarks" are available.
       * @param bookmark  List of bookmarks
       * @param bWritable If false, adding or deleting "My Bookmarks" is disabled
       */
      void onBookmark(List bookmark, boolean bWritable);
  
      /**
       * Invoked in the following scenarios:
       * - Network transmission error
       * - JSON data parsing error
       * - When the 'error' field in the JSON returns a non-zero status code
       */
      void onGetBookmarkError(int nErrorCode);
  
      /**
       * Called when a bookmark is added or updated.
       * @param position  The updated bookmark position (in seconds)
       * @param bUpdated  Status of whether the update was successful
       */
      void onBookmarkUpdated(int position, boolean bUpdated);
  
      /**
       * Called when a bookmark is deleted.
       * @param position  The deleted bookmark position (in seconds)
       * @param bDeleted  Status of whether the deletion was successful
       */
      void onBookmarkDeleted(int position, boolean bDeleted);
  }

3. 비디오 출력 영역 설정

영상 데이터가 렌더링될 대상을 설정합니다. 앱의 구현 방식에 따라 아래 중 하나를 선택합니다.

public void setSurface(Surface surface);

public void setDisplay(SurfaceHolder sh);

4. 콘텐츠 경로 설정

재생 방식(스트리밍 또는 다운로드)에 따라 적절한 메서드를 선택합니다.

스트리밍 콘텐츠

public void setDataSourceByUrl(String path, String extraDrmParam);

파라미터	타입	설명
path	String	재생 URL
extraDrmParam	String	플레이 콜백 시 전달할 추가 파라미터 (값이 없으면 null 입력)

다운로드 콘텐츠

public void setDataSourceByKey(String mediaContentKey, String extraDrmParam, KollusContent content);

파라미터	타입	설명
mediaContentKey	String	다운로드 콘텐츠의 미디어 콘텐츠 키
extraDrmParam	String	DRM 다운로드 콜백 시 전달할 추가 파라미터 (값이 없으면 null 입력)
content	KollusContent	다운로드할 콘텐츠 정보

5~6. 재생 준비 및 데이터 획득

재생에 필요한 리소스를 로드합니다. 재생 준비가 완료되면 onPrepared()가 호출됩니다.

public void prepareAsync();

onPrepared 수신 후 처리 권장 사항

• 콘텐츠 정보 조회: getKollusContent(KollusContent content)를 호출하여 콘텐츠 정보를 가져올 수 있습니다.
• 스크린샷 경로: 파일명.{width}x{height}x{count}.확장자
  • count 중 초기 3장은 의미 없는 값입니다.

String screenShotPath = content.getScreenShotPath();

이어보기 기능 구현

start() 호출 전, 재생 위치를 이동(Seek)하여 이어보기를 구현합니다.

• seekTo(int msec): 지정한 시점과 가장 가까운 키프레임(I-Frame)으로 이동합니다.

mMediaPlayer.seekTo(int msec);

• seekToExact(int msec): 지정한 시점으로 이동합니다.

mMediaPlayer.seekToExact(int msec);  

7. 재생 시작

재생을 시작합니다.

public void start();

8~9. 재생 종료

재생을 완료하거나 중간에 종료할 경우, 아래 메서드를 순서대로 호출하세요.

public void stop();
public void release();

---

북마크 관리 기능 구현

북마크 관리는 콘텐츠 재생 중에 수행할 수 있습니다.

KollusPlayerBookmarkListener를 등록하면 서버와의 동기화 결과를 수신할 수 있습니다. 북마크 작업은 네트워크 상태에 따라 반영 속도가 다를 수 있으므로, 반드시 리스너의 콜백 응답을 확인한 후 UI를 업데이트하세요.

북마크 목록 조회

onBookmark가 호출되면, 현재 북마크 목록을 수신합니다. 이때 특정 시청자의 내 북마크(시청자 개인용 북마크) 쓰기 권한 유무를 확인할 수 있습니다.

북마크 추가 및 수정

특정 시점에 새로운 북마크를 생성거나 기존 내용을 수정합니다.

• 동작 원리: 지정한 위치(position)에 북마크가 없으면 신규 생성, 이미 존재하면 기존 내용을 덮어씁니다.
• 결과 확인: 데이터가 서버에 정상 반영되면 onBookmarkUpdated가 호출됩니다.

public void updateKollusBookmark(int position, String label);

파라미터	타입	설명
position	int	추가 또는 수정할 북마크 위치 (ms)
label	String	북마크 내용 (미지정 시 빈 문자열(""))

북마크 삭제

특정 위치에 저장된 북마크를 제거합니다.

• 결과 확인: 삭제 처리가 완료되면 onBookmarkDeleted가 호출됩니다.

public void deleteKollusBookmark(int position);

파라미터	타입	설명
position	int	삭제할 북마크 위치 (ms)