본문으로 건너뛰기

개발 가이드

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

iOS SDK API 레퍼런스​

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

개요​

Kollus iOS SDK는 iPhone 및 iPad에서 콘텐츠 재생 기능을 통합하고 제어하기 위한 소프트웨어 개발 키트입니다. 본 SDK는 Cocoa Application의 UIView 기반으로 설계되었으며, KollusPlayerView를 서브 뷰(SubView)로 추가하여 플레이어를 화면에 배치할 수 있습니다.

SDK 구성 요소​

KollusStorage​

인증 및 콘텐츠 관리 기능을 담당합니다.

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

KollusPlayerView​

콘텐츠 재생 및 플레이어 기능을 담당합니다.

  • 스트리밍 및 다운로드 콘텐츠 재생
  • 북마크 데이터 조회, 추가, 삭제

KollusStorage​

인스턴스 초기화 및 인증 절차​

kollusStorage 사용 흐름
  1. 앱은 KollusStorage의 init 메서드를 호출하여 인스턴스를 생성합니다.
  2. KollusStorage는 생성된 인스턴스의 식별자(id)를 반환합니다.
  3. 앱은 setApplicationKey 메서드를 통해 인증 키(Application Key)를 설정합니다.
  4. 앱은 setApplicationBundleID 메서드를 통해 앱의 Bundle ID를 설정합니다.
  5. 앱은 setApplicationExpireDate 메서드를 통해 인증 키의 유효 기간(Expire Date)을 설정합니다.
  6. 앱은 startStorage 메서드를 호출하여 인증 절차를 시작합니다.
  7. KollusStorage는 3~5번에서 설정된 값을 기반으로 인증을 진행합니다. 인증 성공 시 YES, 실패 시 NO를 반환합니다.
ℹ️참고

KollusStorage는 인증 키(Application Key), Bundle ID, 인증 키의 유효 기간(Expire Date) 세 가지 값을 기준으로 인증을 수행합니다.
이 중 하나라도 발급된 정보와 일치하지 않을 경우, SDK 초기화가 중단됩니다.

콘텐츠 다운로드​

다운로드​

콘텐츠 다운로드 흐름
  1. 앱은 KollusStorage의 setDelegate 메서드를 호출하여 다운로드 상태를 전달받을 델리게이트를 설정합니다.
  2. 앱은 loadContentURL 메서드를 호출하여 다운로드 대상 콘텐츠의 URL을 설정합니다.
  3. KollusStorage는 해당 URL에 대한 mediaContentKey를 반환합니다.
  4. 앱은 반환된 mediaContentKey를 사용하여 downloadContent 메서드를 호출하고, 콘텐츠 다운로드를 시작합니다.
  5. 다운로드 중 상태가 변경될 때마다, 1번에서 설정한 델리게이트의 kollusStorage:downloadContent:error: 메서드가 호출됩니다.
ℹ️참고

콘텐츠 다운로드 기능은 KollusStorage의 인증이 정상적으로 완료된 경우에만 사용할 수 있습니다.
반드시 스토리지 초기화 및 인증 절차가 완료된 후 다운로드를 시도하세요.

다운로드 콘텐츠 삭제​

다운로드 콘텐츠 삭제 흐름
  1. 앱은 KollusStorage의 removeContent:error: 메서드를 호출하여 콘텐츠 삭제를 요청합니다.
    이때 전달하는 파라미터는 KollusContent.mediaContentKey 값입니다.
  2. KollusStorage는 해당 콘텐츠 삭제를 시도한 뒤, 결과를 반환합니다.
    삭제 성공 시 YES, 실패 시 NO가 반환됩니다.

캐시 데이터 삭제​

캐시 데이터 삭제 흐름
  1. 앱은 KollusStorage의 removeCacheWithError 메서드를 호출하여 현재 관리 중인 캐시 데이터를 삭제합니다.
  2. KollusStorage는 삭제 결과를 반환합니다. 성공 시 YES, 실패 시 NO가 반환됩니다.
ℹ️참고

removeCacheWithError 호출 시, 스트리밍 중인 콘텐츠가 있는 경우 해당 콘텐츠의 캐시 데이터는 삭제되지 않습니다.

콘텐츠 재생​

ℹ️참고

prepareToPlayWithMode: 및 playWithError 메서드는 비동기(async) 방식입니다.
이 메서드들의 실행이 완료되면, 결과는 델리게이트 메서드를 통해 전달됩니다.

따라서, 이들의 실행 결과를 확인하려면 델리게이트로 등록된 객체에 다음 메서드를 미리 구현해 두어야 합니다

  • kollusPlayerView:prepareToPlayWithError:
  • kollusPlayerView:playWithError:

각 델리게이트 메서드의 정의는 KollusPlayerDelegate.h 파일을 참고하세요.

스트리밍​

콘텐츠 재생(스트리밍) 흐름
  1. 앱은 initWithContentURL 메서드를 사용하여 KollusPlayerView 객체를 생성합니다.
  2. KollusPlayerView가 생성되면, 고유 id가 반환됩니다.
  3. 앱은 생성된 KollusPlayerView를 addSubview 메서드를 통해 화면에 출력할 UIView에 추가합니다.
  4. 앱은 기 생성된 KollusStorage 객체를 setStorage 메서드를 통해 KollusPlayerView에 설정합니다.
  5. setDelegate 메서드를 사용하여 KollusPlayerView에 델리게이트를 등록합니다.
  6. 앱은 prepareToPlayWithMode: 메서드를 호출하여 콘텐츠 재생 준비를 요청합니다.
  7. KollusPlayerView는 준비 완료 또는 에러 발생 시, 5번에서 등록한 델리게이트의 kollusPlayerView:prepareToPlayWithError:를 호출하여 결과를 전달합니다.
  8. 콘텐츠 재생 준비가 완료되면, 앱은 playWithError 메서드를 호출하여 콘텐츠 재생을 시작합니다.
  9. 재생이 시작되거나 에러가 발생하면, KollusPlayerView는 델리게이트의 kollusPlayerView:playWithError: 메서드를 호출하여 재생 결과를 전달합니다.

다운로드 콘텐츠​

콘텐츠 재생(다운로드 콘텐츠) 흐름
  1. 앱은 init 메서드를 호출하여 KollusPlayerView 객체를 생성합니다.
  2. KollusPlayerView 객체가 생성되면, 해당 인스턴스의 id가 반환됩니다.
  3. 앱은 재생 화면으로 사용할 UIView 객체에 addSubview 메서드를 사용하여 KollusPlayerView를 추가합니다.
  4. 앱은 setMediaContentKey 메서드를 통해 재생할 콘텐츠의 mediaContentKey를 설정합니다.
  5. 앱은 기 생성된 KollusStorage 인스턴스를 setStorage 메서드를 통해 KollusPlayerView에 설정합니다.
  6. 앱은 setDelegate 메서드를 사용해 KollusPlayerView에 델리게이트를 설정합니다.
  7. 앱은 prepareToPlayWithMode: 메서드를 호출하여 콘텐츠 재생 준비를 요청합니다.
  8. KollusPlayerView는 콘텐츠 준비가 완료되었거나 오류가 발생한 경우, 6번에서 설정된 델리게이트의 kollusPlayerView:prepareToPlayWithError: 메서드를 호출합니다.
  9. 콘텐츠 준비가 완료되면, 앱은 playWithError 메서드를 호출하여 재생을 시작합니다.
  10. KollusPlayerView는 재생이 시작되었거나 오류가 발생한 경우, 델리게이트의 kollusPlayerView:playWithError: 메서드를 호출합니다.

북마크 관리​

재생 중인 콘텐츠의 북마크를 조회, 추가, 삭제할 수 있습니다.

북마크 목록 조회​

북마크 목록 조회 흐름
  1. 앱은 KollusPlayerView의 setBookmarkDelegate 메서드를 호출하여, 북마크 정보를 수신할 델리게이트를 설정합니다.
  2. KollusPlayerView는 콘텐츠 초기화 과정에서, 해당 콘텐츠에 북마크 데이터가 존재하는지 여부를 확인한 후, 1번에서 설정한 델리게이트의 kollusPlayerView:bookmark:enabled:error: 메서드를 통해 결과를 전달합니다.
  3. 델리게이트 메서드를 통해 전달되는 bookmark 파라미터에는 NSArray 형식의 KollusBookmark 객체들이 포함됩니다.
ℹ️참고

북마크 정보는 KollusPlayerView의 콘텐츠 재생 준비 과정에서 함께 처리됩니다.
따라서 setBookmarkDelegate 메서드는 prepareToPlayWithError를 호출하기 이전에 반드시 설정해야 정상적으로 북마크 정보를 수신할 수 있습니다.

북마크 추가​

북마크 추가 흐름
  1. 앱은 KollusPlayerView의 addBookmark:value:error: 메서드를 호출하여 추가할 북마크 정보를 전달하고, 북마크 추가를 요청합니다.
  2. KollusPlayerView는 북마크 추가 결과를 성공 여부와 함께 반환합니다.
ℹ️참고

KollusPlayerView는 내 북마크만 추가 및 삭제할 수 있으며, 공식 북마크는 시청자(End User)가 수정할 수 없습니다.
내 북마크 추가 시, 이미 동일한 위치(position)의 북마크가 존재할 경우, 기존 북마크는 삭제되고 새로운 북마크 정보로 자동 대체됩니다.

북마크 삭제​

북마크 삭제 흐름
  1. 앱은 KollusPlayerView의 removeBookmark:error: 메서드를 호출하여, 삭제할 북마크의 시간 정보(position)를 전달하고 삭제를 요청합니다.
  2. KollusPlayerView는 해당 북마크 삭제 요청에 대한 결과값(성공/실패 여부)을 앱에 반환합니다.
ℹ️참고

KollusPlayerView는 내 북마크만 추가 및 삭제할 수 있으며, 공식 북마크는 시청자(End User가 수정할 수 없습니다.