Danh sách chờ

Tổng quan

Web receiver SDK hỗ trợ xếp hàng bằng hàng đợi mặc định do SDK sử dụng QueueDataQueueManager hoặc sử dụng hàng đợi tuỳ chỉnh bằng cách triển khai cast.framework.QueueBase và sử dụng QueueManager để được cập nhật.

API hàng đợi cho phép các ứng dụng tích hợp tốt hơn với tính năng Truyền bằng cách cung cấp các tính năng sau:

  • Hỗ trợ triển khai hàng đợi trên đám mây của Google và của đối tác bên ngoài để hàng đợi được lưu trữ và tạo có thể được tải trực tiếp vào Thiết bị truyền.
  • Cơ chế cho phép phân trang các mục trong hàng đợi thay vì tải làm mọi thứ cùng một lúc.
  • Hỗ trợ tính năng nhắn tin mới, chẳng hạn như chuyển đến mục tiếp theo, mục trước, tìm nạp một cửa sổ các mục, cũng như nhận thông tin đa phương tiện liên quan đến một tập hợp các mục hàng đợi.
  • Chiến lược phát hành đĩa đơn QueueManager để quản lý việc chèn, xoá và cập nhật các mục trong hàng đợi.

Hàng đợi mặc định

Web receiver SDK hỗ trợ hàng đợi có giới hạn ngay từ đầu trong biểu mẫu của hàng đợi mặc định.

Để sử dụng hàng đợi mặc định, hãy cung cấp queueData trong LoadRequestData của lượt tải phía người gửi hoặc gửi một yêu cầu tải cục bộ đang sử dụng PlayerManager#load. Xem thêm phần Tải nội dung nghe nhìn.

Ở phía người nhận, hàng đợi có thể được sửa đổi bằng cách sử dụng QueueManager sau khi đã tải nội dung nghe nhìn ban đầu.

Hàng đợi tuỳ chỉnh

Nếu hàng đợi mặc định không cung cấp chức năng xếp hàng cần thiết cho của bạn, bạn có thể tạo hàng đợi tuỳ chỉnh, cho phép người dùng và tính linh hoạt.

Nhà phát triển ứng dụng có thể tạo hàng đợi bên Trình nhận web bằng cách triển khai cast.framework.QueueBase.

Dưới đây là ví dụ cơ bản về một hàng đợi đơn giản trong đó initialize lệnh gọi sẽ bị ghi đè, sau đó là danh sách các mục trong hàng đợi cùng với nội dung mô tả hàng đợi được cung cấp cho Thiết bị truyền.

Xem thêm phần Tải nội dung nghe nhìn.

// 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;
 }
};

Trong ví dụ này, danh sách các mục trong initialize được cung cấp trong QueueBase lệnh gọi hàm khởi tạo. Tuy nhiên, để triển khai hàng đợi đám mây, Web tuỳ chỉnh Logic của người nhận có thể tìm nạp các mục từ bên ngoài rồi trả về các mục đó như một phần của lệnh gọi khởi tạo.

Bản minh hoạ dưới đây là minh hoạ cách sử dụng API xếp hàng một cách toàn diện hơn hàng đợi triển khai hầu hết Lớp 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);
 }
};

Trong ví dụ trên, YourServer là máy chủ hàng đợi trên đám mây và có logic về cách tìm nạp một số mục nội dung nghe nhìn nhất định.

Để sử dụng QueueBase triển khai hàng đợi, một tuỳ chọn sẽ đặt tuỳ chọn hàng đợi trong CastReceiverContext:

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

Quản lý danh sách chờ

Chiến lược phát hành đĩa đơn QueueManager giúp nhà phát triển linh hoạt trong việc phát triển các giải pháp xếp hàng đợi bằng cách cung cấp để truy cập danh sách các mục hàng đợi hiện đang được lưu trữ cũng như mục đang phát. API này cũng cung cấp các thao tác như chèn, xoá, và cập nhật các mục trong hàng đợi. Đoạn mã sau đây cho biết cách truy cập vào bản sao của QueueManager:

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

Quản lý hàng đợi mặc định

Sau khi hàng đợi ban đầu đã được tải, QueueManager có thể dùng để thực hiện các thao tác như truy xuất mục hiện tại, truy xuất tất cả các mục trong hàng đợi và cập nhật các mục trong hàng đợi bằng insertItems, removeItems, và updateItems.

Quản lý hàng đợi tuỳ chỉnh

Dưới đây là ví dụ về cách triển khai hàng đợi tuỳ chỉnh sử dụng tính năng chèn và dựa trên một số sự kiện. Ví dụ này cũng minh hoạ cách sử dụng updateItems nơi nhà phát triển có thể sửa đổi các mục trong hàng đợi hiện có, chẳng hạn như xoá điểm chèn quảng cáo.

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;
    }));
  }
};

Tin nhắn đến và đi

Để hỗ trợ đầy đủ tính năng tìm nạp hàng đợi phía người nhận là nguồn đáng tin cậy, các thông báo trong hàng đợi bổ sung do CAF giới thiệu và xử lý SDK của bộ thu:

Thông báo đến Tham số Tin nhắn trả lời đi Quay lại
TIẾP THEO Không cần tham số. MEDIA_STATUS Người nhận sẽ (tìm nạp qua nextItems() nếu cần) và bắt đầu phát mục tiếp theo.
TRƯỚC ĐÂY Không cần tham số. MEDIA_STATUS Trình nhận web sẽ (tìm nạp thông qua previousItems() nếu cần) và bắt đầu đang phát mục trước.
FETCH_ITEMS FetchItemsRequestData QUEUE_CHANGE Cast.framework.messages.QueueChange. Ví dụ: đối với trường hợp chèn, trường items trong JSON sẽ chứa danh sách các mặt hàng mới được tìm nạp.
GET_ITEMS_INFO GetItemsInfoRequestData chứa itemIds: Mảng<number> ITEMS_INFO Cast.framework.messages.ItemsInfo có thông tin về mục trong hàng đợi.
GET_QUEUE_IDS Không cần tham số. QUEUE_IDS cast.framework.messages.QueueIds.

Đối với NEXT/PREVIOUS, nếu nội dung biểu thị hàng đợi hiện có trên Web receiver không có thêm mục nào, QueueBase.nextItems() hoặc QueueBase.prevItems() tự động được gọi để nhận thêm mặt hàng.

Đối với FETCH_ITEM, hàm tương ứng fetchItems trong quá trình triển khai QueueBase được gọi cho hàng đợi đám mây. Hàng đợi này sẽ truy xuất dữ liệu liên quan cần trả về Web receiver để lưu trữ.

Bất cứ khi nào tìm nạp thêm mục, loại thông báo mới QUEUE_CHANGE sẽ được kích hoạt và gửi lại cho người gửi. Xem các loại các thay đổi về hàng đợi.

Đối với GET_ITEMS_INFO, QueueBase Quá trình triển khai không được kích hoạt và Web receiver trả về thông tin nội dung nghe nhìn đã biết với danh sách id.

Đang xáo trộn hàng đợi

Để đặt các mục trong hàng đợi của bạn thành được xáo trộn, hãy đặt shuffle cờ của QueueData vào true khi tải các mục của bạn vào hàng đợi.

Nếu bạn đang sử dụng phương thức triển khai QueueBase, sử dụng thời gian shuffle để trả về danh sách các mục đã xáo trộn.

Để phát ngẫu nhiên một hàng đợi hiện có, hãy sử dụng shuffle cờ của QUEUE_UPDATE MessageType, thay vì lệnh QUEUE_SHUFFLE. Vui lòng xem QueueUpdateRequestData để biết thêm thông tin.

Chế độ lặp lại

Để đặt các mục trong hàng đợi của bạn thành lặp lại, hãy đặt repeatMode thuộc tính của QueueData thành sự kiện mong muốn RepeatMode khi tải các mục vào hàng đợi.

Để thay đổi RepeatMode của một hàng đợi hiện có, hãy sử dụng repeatMode thuộc tính của QueueUpdateRequestData, Phương thức này sử dụng QUEUE_UPDATE MessageType