본문으로 건너뛰기

개발 가이드

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

iOS SDK API 레퍼런스​

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

개요​

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

핵심 구성 요소​

KollusStorage​

SDK 인증 및 콘텐츠 관리를 담당하는 클래스입니다.

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

KollusPlayerView​

콘텐츠 재생 및 플레이어 제어를 담당하는 클래스입니다.

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

KollusStorage​

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

kollusStorage 사용 흐름
  1. 앱은 KollusStorage의 init 메서드를 호출하여 인스턴스를 생성합니다.
  2. 인스턴스가 정상적으로 생성되면, 해당 인스턴스의 식별자(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 메서드를 호출하여 다운로드 상태를 전달받을 델리게이트(Delegate)를 등록합니다.
  2. 앱은 loadContentURL 메서드를 호출하여 다운로드할 콘텐츠의 URL을 설정합니다.
  3. KollusStorage는 해당 URL을 분석하여 대상 콘텐츠의 고유 식별자인 mediaContentKey를 반환합니다.
  4. 앱은 반환된 mediaContentKey를 파라미터로 사용하여 downloadContent 메서드를 호출하고, 다운로드를 시작합니다.
  5. KollusStorage는 다운로드 중 상태가 변경될 때마다, 1번에서 등록한 델리게이트의 kollusStorage:downloadContent:error: 메서드를 호출합니다.
ℹ️참고

콘텐츠 다운로드 기능은 KollusStorage의 인증이 정상적으로 완료된 상태에서만 작동합니다. 반드시 스토리지 초기화 및 인증 성공 후 다운로드를 시도하세요.

다운로드 콘텐츠 삭제​

다운로드 콘텐츠 삭제 흐름
  1. 앱은 KollusStorage의 removeContent:error: 메서드에 삭제할 콘텐츠의 키(mediaContentKey)를 전달하여 삭제를 요청합니다.
  2. KollusStorage는 로컬 저장소에서 해당 콘텐츠를 삭제한 후 결과를 반환합니다. 삭제 성공 시 YES, 실패 시 NO가 반환됩니다.

캐시 데이터 삭제 구현​

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

removeCacheWithError 호출 시점에 스트리밍 재생 중인 콘텐츠가 있다면, 안정적인 재생 유지를 위해 해당 콘텐츠의 캐시 데이터는 삭제 대상에서 제외됩니다.

콘텐츠 재생 구현​

ℹ️비동기 처리 안내

prepareToPlayWithMode: 및 playWithError 메서드는 비동기 방식으로 동작합니다. 이 메서드들의 실행 결과는 반환값이 아닌 델리게이트 메서드를 통해 전달됩니다.

정상적인 동작 확인을 위해 델리게이트로 등록된 객체에 아래 메서드들을 반드시 사전에 구현해야 합니다

  • kollusPlayerView:prepareToPlayWithError:
  • kollusPlayerView:playWithError:

상세한 델리게이트 정의는 KollusPlayerDelegate.h 파일을 참고하세요.

스트리밍 재생​

콘텐츠 재생(스트리밍) 흐름
  1. 앱은 initWithContentURL 메서드를 사용하여 재생 URL 정보가 포함된 KollusPlayerView 인스턴스를 생성합니다.
  2. 인스턴스가 정상적으로 생성되면, 해당 인스턴스의 식별자(id)가 반환됩니다.
  3. 앱은 생성된 KollusPlayerView를 addSubview 메서드를 사용하여 화면에 출력될 상위 UIView의 서브뷰로 추가합니다.
  4. 앱은 이전에 생성해 둔 KollusStorage 객체를 setStorage 메서드를 통해 KollusPlayerView에 연결합니다.
  5. 앱은 setDelegate 메서드를 호출하여 플레이어의 상태 이벤트를 수신할 델리게이트를 등록합니다.
  6. 앱은 prepareToPlayWithMode: 메서드를 호출하여 재생 준비를 요청합니다.
  7. KollusPlayerView는 준비 완료 또는 오류 발생 시, 5번에서 등록한 델리게이트의 kollusPlayerView:prepareToPlayWithError:를 호출하여 결과를 전달합니다.
  8. 재생 준비가 완료되면, 앱은 playWithError 메서드를 호출하여 재생을 시작합니다.
  9. 재생이 시작되거나 오류가 발생하면, KollusPlayerView는 델리게이트의 kollusPlayerView:playWithError: 메서드를 호출하여 최종 결과를 전송합니다.

다운로드 콘텐츠 재생​

콘텐츠 재생(다운로드 콘텐츠) 흐름
  1. 앱은 init 메서드를 호출하여 KollusPlayerView 인스턴스를 생성합니다.
  2. 인스턴스가 정상적으로 생성되면, 해당 인스턴스의 식별자(id)가 반환됩니다.
  3. 앱은 재생 화면을 구성할 UIView 객체에 addSubview 메서드를 사용하여 생성된 플레이어 뷰를 추가합니다.
  4. 앱은 setMediaContentKey 메서드를 사용하여 재생할 콘텐츠의 식별자(mediaContentKey)를 설정합니다.
  5. 앱은 이전에 생성해 둔 KollusStorage 객체를 setStorage 메서드를 통해 KollusPlayerView에 연결합니다.
  6. 앱은 setDelegate 메서드를 호출하여 플레이어의 상태 이벤트를 수신할 델리게이트를 등록합니다.
  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의 재생 준비 과정에서 함께 처리됩니다. 따라서 prepareToPlayWithError를 호출하기 전에 반드시 setBookmarkDelegate 메서드를 설정해야 정상적으로 북마크 데이터를 수신할 수 있습니다.

북마크 추가​

북마크 추가 흐름
  1. 앱은 KollusPlayerView의 addBookmark:value:error: 메서드를 호출하여 생성할 북마크의 시점 및 내용을 전달하고 추가를 요청합니다.
  2. KollusPlayerView는 북마크 추가 요청의 처리 결과를 즉시 반환합니다.
ℹ️데이터 업데이트 정책
  • 업데이트 권한: 시청자는 '내 북마크'에 한해 추가 및 삭제 권한을 가집니다. (고객사가 설정한 공식 북마크는 수정할 수 없습니다.)
  • 기존 데이터 대체: 새로운 북마크 추가 시, 동일한 시점(position)에 이미 북마크가 존재한다면 기존 데이터는 삭제되고 새 데이터로 자동 업데이트됩니다.

북마크 삭제​

북마크 삭제 흐름
  1. 앱은 KollusPlayerView의 removeBookmark:error: 메서드를 호출하여 삭제할 북마크의 시점을 전달하고 삭제를 요청합니다.
  2. KollusPlayerView는 북마크 삭제 요청의 처리 결과를 즉시 반환합니다.
ℹ️참고

북마크 삭제 기능 역시 시청자가 직접 생성한 '내 북마크'에 대해서만 유효합니다. (고객사가 설정한 공식 북마크는 삭제할 수 없습니다.)