Mengantre

Ringkasan

Web Receiver SDK mendukung antrean dengan antrean default yang disediakan oleh SDK menggunakan QueueData dan QueueManager atau menggunakan antrean kustom dengan mengimplementasikan cast.framework.QueueBase dan menggunakan QueueManager untuk update.

Queueing API memungkinkan aplikasi untuk lebih mudah berintegrasi dengan Cast dengan menyediakan fitur berikut:

  • Dukungan untuk implementasi antrean cloud Google dan partner sehingga antrean yang disimpan dan dibuat secara eksternal dapat langsung dimuat ke perangkat Cast.
  • Mekanisme yang memungkinkan penomoran halaman item dalam antrean, bukan memuat semuanya sekaligus.
  • Dukungan untuk pesan baru seperti membuka item berikutnya, item sebelumnya, mengambil jendela item, serta mendapatkan informasi media yang terkait dengan sekumpulan item antrean.
  • QueueManager untuk mengelola penyisipan, penghapusan, dan pembaruan item antrean.

Antrean default

Web Receiver SDK menyediakan dukungan antrean terbatas di luar kotak dalam bentuk antrean default.

Untuk menggunakan antrean default, berikan queueData di LoadRequestData pemuatan sisi pengirim atau kirim permintaan pemuatan lokal menggunakan PlayerManager#load. Lihat juga Memuat media.

Di sisi penerima, antrean dapat diubah menggunakan QueueManager setelah media awal dimuat.

Antrean khusus

Jika antrean default tidak menyediakan fungsi antrean yang diperlukan untuk aplikasi Anda, kemampuan untuk membuat antrean kustom akan tersedia, sehingga memungkinkan lebih banyak kemampuan dan fleksibilitas.

Developer aplikasi dapat membuat antrean samping Penerima Web dengan mengimplementasikan cast.framework.QueueBase.

Berikut adalah contoh dasar antrean sederhana tempat panggilan initialize diganti, lalu daftar item antrean beserta deskripsi antrean disediakan ke perangkat Cast.

Lihat juga Memuat media.

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

Dalam contoh ini, daftar item dalam panggilan initialize disediakan dalam panggilan konstruktor QueueBase penyedia. Namun, untuk implementasi antrean cloud, logika Penerima Web kustom dapat mengambil item secara eksternal, lalu menampilkannya sebagai bagian dari panggilan inisialisasi.

Untuk menunjukkan penggunaan API antrean yang lebih komprehensif, berikut adalah antrean Demo yang menerapkan sebagian besar class 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);
 }
};

Pada contoh di atas, YourServer adalah server antrean cloud dan memiliki logika tentang cara mengambil item media tertentu.

Untuk menggunakan antrean yang diimplementasikan QueueBase, seseorang harus menetapkan opsi antrean di CastReceiverContext:

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

Mengelola antrean

QueueManager memberi developer fleksibilitas dalam mengembangkan solusi antrean mereka dengan menyediakan metode untuk mengakses daftar item antrean yang saat ini disimpan serta item yang sedang diputar. Layanan ini juga menyediakan operasi seperti penyisipan, penghapusan, dan pembaruan item antrean. Cuplikan berikut menunjukkan cara mengakses instance QueueManager:

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

Pengelolaan antrean default

Setelah antrean awal dimuat, QueueManager dapat digunakan untuk melakukan tindakan seperti mengambil item saat ini, mengambil semua item dalam antrean, dan memperbarui item dalam antrean menggunakan insertItems, removeItems, dan updateItems.

Pengelolaan antrean kustom

Berikut adalah contoh implementasi antrean kustom yang menggunakan metode penyisipan dan penghapusan berdasarkan beberapa peristiwa. Contoh ini juga menunjukkan penggunaan updateItems yang memungkinkan developer mengubah item antrean di antrean yang ada, seperti menghapus jeda iklan.

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

Pesan masuk dan keluar

Untuk sepenuhnya mendukung pengambilan antrean sisi penerima sebagai sumber kebenaran, pesan antrean tambahan berikut diperkenalkan dan ditangani oleh CAF Receiver SDK:

Pesan Masuk Parameter Pesan Respons Keluar Kembali
BERIKUTNYA Tidak perlu parameter. STATUS_MEDIA Penerima akan (mengambil nextNext()() jika perlu) dan mulai memutar item berikutnya.
SEBELUMNYA Tidak perlu parameter. STATUS_MEDIA Penerima Web akan (mengambil melalui prevItems() jika diperlukan) dan mulai memutar item sebelumnya.
FETCH_ITEMS FetchItemsRequestData QU_E_CHANGE Cast.framework.messages.QueueChange. Misalnya, untuk kasus penyisipan, kolom item di JSON akan berisi daftar item baru yang diambil.
GET_ITEMS_INFO GetItemsInfoRequestData berisi itemIds: Array<number> INFO_ITEM cast.framework.messages.ItemsInfo dengan informasi item antrean.
GET_QUEUE_IDS Tidak perlu parameter. QUEUE_IDS cast.framework.messages.QueueIds.

Untuk NEXT/PREVIOUS, jika representasi antrean yang ada di Penerima Web tidak memiliki lebih banyak item, QueueBase.nextItems() atau QueueBase.prevItems() otomatis dipanggil untuk menerima lebih banyak item.

Untuk FETCH_ITEM, fungsi fetchItems yang sesuai dalam implementasi QueueBase dipanggil untuk antrean cloud, yang mengambil data yang relevan untuk ditampilkan ke Penerima Web untuk disimpan.

Setiap kali item lain diambil, jenis pesan baru QUEUE_CHANGE akan dipicu dan dikirim kembali ke pengirim. Lihat berbagai jenis perubahan antrean.

Untuk GET_ITEMS_INFO, implementasi QueueBase tidak dipicu dan Penerima Web menampilkan informasi media yang sudah diketahui oleh daftar ID.

Mengacak antrean

Untuk menetapkan item dalam antrean agar diacak, tetapkan tanda shuffle dari QueueData ke true saat memuat item ke antrean.

Jika Anda menggunakan implementasi QueueBase, gunakan metode shuffle untuk menampilkan daftar item yang diacak.

Untuk mengacak antrean yang ada, gunakan tanda shuffle dari QUEUE_UPDATE MessageType, bukan perintah QUEUE_SHUFFLE. Lihat QueueUpdateRequestData untuk mengetahui informasi selengkapnya.

Mode berulang

Untuk menetapkan item dalam antrean agar diulang, tetapkan properti repeatMode QueueData ke RepeatMode yang diinginkan saat memuat item ke antrean.

Untuk mengubah RepeatMode antrean yang ada, gunakan properti repeatMode dari QueueUpdateRequestData, yang menggunakan QUEUE_UPDATE MessageType.