개요

웹 수신기 SDK는 QueueDataQueueManager를 사용하여 SDK에서 제공하는 기본 큐를 대기열에 추가하거나 업데이트를 위해 cast.framework.QueueBase를 구현하고 QueueManager를 사용하여 커스텀 큐를 사용합니다.

Queueing API를 사용하면 애플리케이션에서 다음 기능을 제공하여 Cast와 더 잘 통합할 수 있습니다.

  • 외부에서 저장되고 생성된 큐를 Cast 기기에 직접 로드할 수 있도록 Google 및 파트너의 클라우드 큐 구현을 지원합니다.
  • 모든 것을 한 번에 로드하는 대신 큐에 항목을 페이지로 나누는 메커니즘
  • 다음 항목, 이전 항목으로 이동, 항목 창 가져오기, 일련의 큐 항목과 관련된 미디어 정보 가져오기와 같은 새 메시지를 지원합니다.
  • 큐 항목의 삽입, 삭제, 업데이트를 관리하는 QueueManager

기본 대기열

웹 수신기 SDK는 기본 큐 형식의 즉시 큐 지원을 제공합니다.

기본 대기열을 사용하려면 발신자 측 로드의 LoadRequestDataqueueData를 제공하거나 PlayerManager#load를 사용하여 로컬 로드 요청을 보냅니다. 미디어 로드도 참고하세요.

수신자 측에서 초기 미디어가 로드된 후 QueueManager를 사용하여 큐를 수정할 수 있습니다.

맞춤 대기열

기본 큐가 앱에 필요한 큐 기능을 제공하지 않는 경우, 커스텀 큐를 만드는 기능을 사용하여 더 많은 기능과 유연성을 확보할 수 있습니다.

애플리케이션 개발자는 cast.framework.QueueBase를 구현하여 웹 수신기를 추가합니다.

다음은 initialize 호출이 재정의되고 큐 설명과 함께 큐 항목 목록이 Cast 기기에 제공되는 간단한 큐의 기본적인 예입니다.

미디어 로드도 참고하세요.

// Creates a simple queue with a combination of contents.
const DemoQueue = class extends cast.framework.QueueBase {
 constructor() {
   super();

   /**
    * List of media urls.
    * @private @const {!Array<string>}
    */
   this.myMediaUrls_ = [...];
 }
 /**
  * Provide a list of items.
  * @param {!cast.framework.messages.LoadRequestData} loadRequestData
  * @return {!cast.framework.messages.QueueData}
  */
 initialize(loadRequestData) {
   const items = [];
   for (const mediaUrl of this.myMediaUrls_) {
     const item = new cast.framework.messages.QueueItem();
     item.media = new cast.framework.messages.MediaInformation();
     item.media.contentId = mediaUrl;
     items.push(item);
   }
   let queueData = loadRequestData.queueData;
   // Create a new queue with media from the load request if one doesn't exist.
   if (!queueData) {
     queueData = new cast.framework.messages.QueueData();
     queueData.name = 'Your Queue Name';
     queueData.description = 'Your Queue Description';
     queueData.items = items;
     // Start with the first item in the playlist.
     queueData.startIndex = 0;
     // Start from 10 seconds into the first item.
     queueData.currentTime = 10;
   }
   return queueData;
 }
};

이 예에서는 initialize 호출의 항목 목록이 제공자의 QueueBase 생성자 호출에 제공됩니다. 하지만 클라우드 큐 구현의 경우 맞춤 웹 수신자 로직은 항목을 외부에서 가져온 다음 초기화 호출의 일부로 반환할 수 있습니다.

다음은 대기열 API를 더 포괄적으로 사용하는 방법을 보여주기 위해 대부분의 QueueBase 클래스를 구현하는 데모 대기열입니다.

const DemoQueue = class extends cast.framework.QueueBase {
 constructor() {
   /** @private {} */
   super();
   YourServer.onSomeEvent = this.updateEntireQueue_;
 }

 /**
  * Initializes the queue.
  * @param {!cast.framework.messages.LoadRequestData} loadRequestData
  * @return {!cast.framework.messages.QueueData}
  */
 initialize(loadRequestData) {
   let queueData = loadRequestData.queueData;
   // Create a new queue with media from the load request if one doesn't exist.
   if (!queueData) {
     queueData = new cast.framework.messages.QueueData();
     queueData.name = 'Your Queue Name';
     queueData.description = 'Your Queue Description';
     // Put the first set of items into the queue
     const items = this.nextItems();
     queueData.items = items;
     // Start with the first item in the playlist.
     queueData.startIndex = 0;
     // Start from 10 seconds into the first item.
     queueData.currentTime = 10;
   }
   return queueData;
 }

 /**
  * Picks a set of items from remote server after the reference item id and
  * return as the next items to be inserted into the queue. When
  * referenceItemId is omitted, items are simply appended to the end of the
  * queue.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 nextItems(referenceItemId) {
   // Assume your media has a itemId and the media url
   return this.constructQueueList_(YourServer.getNextMedias(referenceItemId));
 }

 /**
  * Picks a set of items from remote server before the reference item id and
  * return as the items to be inserted into the queue. When
  * referenceItemId is omitted, items are simply appended to beginning of the
  * queue.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 prevItems(referenceItemId) {
   return this.constructQueueList_(YourServer.getPrevMedias(referenceItemId));
 }

 /**
  * Constructs a list of QueueItems based on the media information containing
  * the item id and the media url.
  * @param {number} referenceItemId
  * @return {!Array<cast.framework.QueueItem>}
  */
 constructQueueList_(medias) {
   const items = [];
   for (media of medias) {
     const item = new cast.framework.messages.QueueItem(media.itemId);
     item.media = new cast.framework.messages.MediaInformation();
     item.media.contentId = media.url;
     items.push(item);
   }
   return items;
 }

 /**
  * Logs the currently playing item.
  * @param {number} itemId The unique id for the item.
  * @export
  */
 onCurrentItemIdChanged(itemId) {
   console.log('We are now playing video ' + itemId);
   YourServer.trackUsage(itemId);
 }
};

위의 예시에서 YourServer는 클라우드 큐 서버이며 특정 미디어 항목을 가져오는 방법에 관한 로직이 있습니다.

QueueBase 구현 큐를 사용하려면 CastReceiverContext에서 큐 옵션을 설정합니다.

const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});

큐 관리

QueueManager는 현재 저장된 대기열 항목과 현재 재생 항목에 액세스하는 메서드를 제공하여 개발자가 대기열 솔루션을 개발할 수 있는 유연성을 제공합니다. 큐 항목의 삽입, 삭제, 업데이트와 같은 작업도 제공합니다. 다음 스니펫은 QueueManager의 인스턴스에 액세스하는 방법을 보여줍니다.

const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();

기본 큐 관리

초기 큐가 로드되면 QueueManager를 사용하여 현재 항목 검색, 큐의 모든 항목 검색, 큐의 항목 업데이트와 같은 작업을 insertItems, removeItems, updateItems와 같은 작업에 사용할 수 있습니다.

커스텀 큐 관리

다음은 일부 이벤트를 기반으로 삽입 및 삭제 메서드를 사용하는 맞춤 큐 구현의 예입니다. 또한 이 예에서는 개발자가 광고 시간 삭제와 같이 기존 큐에서 큐 항목을 수정할 수 있는 updateItems의 사용도 보여줍니다.

const DemoQueue = class extends cast.framework.QueueBase {
  constructor() {
    super();

    /** @private @const {!cast.framework.QueueManager} */
    this.queueManager_ = context.getPlayerManager().getQueueManager();
  }

  /**
   * Provide a list of items.
   * @param {!cast.framework.messages.LoadRequestData} loadRequestData
   * @return {!cast.framework.messages.QueueData}
   */
  initialize(loadRequestData) {
    // Your normal initialization; see examples above.
    return queueData;
  }

  /** Inserts items to the queue. */
  onSomeEventTriggeringInsertionToQueue() {
    const twoMoreUrls = ['http://url1', 'http://url2'];
    const items = [];
    for (const mediaUrl of twoMoreUrls) {
      const item = new cast.framework.QueueItem();
      item.media = new cast.framework.messages.MediaInformation();
      item.media.contentId = mediaUrl;
      items.push(item);
    }
    // Insert two more items after the current playing item.
    const allItems = this.queueManager_.getItems();
    const currentItemIndex = this.queueManager_.getCurrentItemIndex();
    const nextItemIndex = currentItemIndex + 1;
    let insertBefore = undefined;
    if (currentItemIndex >= 0 &&
        currentItemIndex < allItems.length - 1) {
      insertBefore = allItems[nextItemIndex].itemId;
    }
    this.queueManager_.insertItems(items, insertBefore);
  }

  /** Removes a particular item from the queue. */
  onSomeEventTriggeringRemovalFromQueue() {
    this.queueManager_.removeItems([2]);
  }

  /** Removes all the ads from all the items across the entire queue. */
  onUserBoughtAdFreeVersion() {
    const items = this.queueManager_.getItems();
    this.queueManager_.updateItems(items.map(item => {
      item.media.breaks = undefined;
      return item;
    }));
  }
};

수신 및 발신 메일

수신자 측 대기열 가져오기를 정보 소스로 완전히 지원하기 위해 CAF 수신기 SDK에서 다음과 같은 추가 대기열 메시지를 도입하고 처리합니다.

수신 메시지 매개변수 발신 응답 메시지 Return 키
다음 매개변수가 필요하지 않습니다. MEDIA_STATUS 수신기는 (필요한 경우 nextItems()를 통해 가져온) 다음 항목 재생을 시작합니다.
이전 매개변수가 필요하지 않습니다. MEDIA_STATUS 웹 수신기가 (필요한 경우 prevItems()를 통해 가져오기) 이전 항목 재생을 시작합니다.
FETCH_ITEMS FetchItemsRequestData QUEUE_CHANGE Cast.framework.messages.QueueChange. 예를 들어, 삽입 사례의 경우 JSON의 항목 필드에 가져온 새 항목 목록이 포함됩니다.
GET_ITEMS_INFO itemIds가 포함된 GetItemsInfoRequestData: 배열<number> 상품 정보 cast.framework.messages.ItemsInfo와 함께 큐 항목 정보를 제공합니다.
GET_QUEUE_IDS 매개변수가 필요하지 않습니다. QUEUE_IDS cast.framework.messages.QueueIds

NEXT/PREVIOUS의 경우 웹 수신기의 기존 큐 표현에 더 많은 항목이 없으면 QueueBase.nextItems() 또는 QueueBase.prevItems()가 자동으로 호출되어 더 많은 항목을 수신합니다.

FETCH_ITEM의 경우 QueueBase 구현에서 상응하는 함수 fetchItems가 클라우드 큐에 호출되고, 이는 저장된 데이터를 저장하기 위해 웹 수신기에 반환될 관련 데이터를 검색합니다.

더 많은 항목을 가져올 때마다 새 메시지 유형 QUEUE_CHANGE가 트리거되어 발신자에게 다시 전송됩니다. 다양한 유형의 큐 변경사항을 참고하세요.

GET_ITEMS_INFO의 경우 QueueBase 구현이 트리거되지 않으며 웹 수신기는 이미 ID 목록에 알려진 미디어 정보를 반환합니다.

큐 셔플

큐의 항목을 셔플하도록 설정하려면 큐로 항목을 로드할 때 QueueDatashuffle 플래그를 true로 설정합니다.

QueueBase 구현을 사용하고 있다면 shuffle 메서드를 사용하여 셔플된 항목 목록을 반환합니다.

기존 큐를 셔플하려면 QUEUE_SHUFFLE 명령어 대신 QUEUE_UPDATE MessageTypeshuffle 플래그를 사용합니다. 자세한 내용은 QueueUpdateRequestData를 참고하세요.

반복 모드

큐의 항목을 반복하도록 설정하려면 큐로 항목을 로드할 때 QueueDatarepeatMode 속성을 원하는 RepeatMode로 설정합니다.

기존 큐의 RepeatMode를 변경하려면 QUEUE_UPDATE MessageType를 사용하는 QueueUpdateRequestDatarepeatMode 속성을 사용합니다.