در صف

نمای کلی

Web Receiver SDK از صف بندی با صف پیش فرض ارائه شده توسط SDK با استفاده از QueueData و QueueManager یا استفاده از یک صف سفارشی با پیاده سازی cast.framework.QueueBase و استفاده از QueueManager برای به روز رسانی پشتیبانی می کند.

Queuing API به برنامه‌ها اجازه می‌دهد تا با ارائه ویژگی‌های زیر بهتر با Cast یکپارچه شوند:

  • پشتیبانی از اجرای صف ابری Google و شریک به طوری که صف های ذخیره شده و ایجاد شده خارجی را می توان مستقیماً در دستگاه های Cast بارگیری کرد.
  • مکانیسم هایی که به جای بارگیری همه چیز به یکباره، امکان صفحه بندی موارد در صف را فراهم می کند.
  • پشتیبانی از پیام‌های جدید مانند رفتن به مورد بعدی، مورد قبلی، واکشی پنجره‌ای از آیتم‌ها، و همچنین دریافت اطلاعات رسانه مربوط به مجموعه‌ای از آیتم‌های صف.
  • QueueManager برای مدیریت درج، حذف و به روز رسانی آیتم های صف.

صف پیش فرض

Web Receiver SDK پشتیبانی از صف محدود خارج از جعبه را در قالب یک صف پیش فرض فراهم می کند.

برای استفاده از صف پیش‌فرض، queueData در LoadRequestData بارگیری‌های سمت فرستنده خود ارائه دهید یا با استفاده از 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 ارائه دهنده ارائه شده است. با این حال، برای اجرای صف ابری، منطق Web Receiver سفارشی می تواند موارد را به صورت خارجی واکشی کند و سپس آنها را به عنوان بخشی از تماس اولیه بازگرداند.

برای نشان دادن استفاده جامع تر از 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 -Implemented queueing، می‌توان گزینه صف را در 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;
    }));
  }
};

پیام های ورودی و خروجی

برای پشتیبانی کامل از واکشی صف سمت گیرنده به عنوان منبع حقیقت، پیام‌های صف اضافی زیر توسط SDK گیرنده CAF معرفی و مدیریت می‌شوند:

پیام دریافتی پارامترها پیام پاسخ خروجی بازگشت
بعدی هیچ پارامتری لازم نیست MEDIA_STATUS گیرنده (در صورت لزوم از طریق nextItems() واکشی می کند) و شروع به پخش آیتم بعدی می کند.
قبلی هیچ پارامتری لازم نیست MEDIA_STATUS گیرنده وب (در صورت لزوم از طریق prevItems() واکشی می کند) و شروع به پخش آیتم قبلی می کند.
FETCH_ITEMS FetchItemsRequestData QUEUE_CHANGE cast.framework.messages.QueueChange. به عنوان مثال، برای یک مورد درج، فیلد موارد در JSON حاوی لیست موارد جدید واکشی شده است.
GET_ITEMS_INFO GetItemsInfoRequestData حاوی itemIds : Array<number> ITEMS_INFO cast.framework.messages.ItemsInfo با اطلاعات مورد صف.
GET_QUEUE_IDS هیچ پارامتری لازم نیست QUEUE_IDS cast.framework.messages.QueueIds.

برای NEXT / PREVIOUS ، اگر نمایش صف موجود در گیرنده وب موارد بیشتری نداشته باشد، QueueBase.nextItems() یا QueueBase.prevItems() به طور خودکار برای دریافت موارد بیشتر فراخوانی می شود.

برای FETCH_ITEM ، تابع مربوطه fetchItems در اجرای QueueBase برای صف‌های ابری فراخوانی می‌شود، که داده‌های مربوطه را بازیابی می‌کند تا برای ذخیره به گیرنده وب برگردانده شود.

هر زمان که موارد بیشتری واکشی شوند، یک نوع پیام جدید از نوع QUEUE_CHANGE فعال می شود و برای فرستنده ارسال می شود. انواع مختلف تغییرات صف را ببینید.

برای GET_ITEMS_INFO ، اجرای QueueBase فعال نمی‌شود و گیرنده وب اطلاعات رسانه‌ای را که قبلاً به فهرست شناسه‌ها شناخته شده است، برمی‌گرداند.

به هم زدن یک صف

برای اینکه آیتم‌های موجود در صف خود را با هم مخلوط کنید، هنگام بارگیری آیتم‌های خود در صف، پرچم shuffle QueueData را روی true تنظیم کنید.

اگر از یک پیاده سازی QueueBase استفاده می کنید، از متد shuffle برای برگرداندن یک لیست به هم ریخته از آیتم ها استفاده کنید.

برای به هم زدن یک صف موجود، به جای دستور QUEUE_SHUFFLE ، از پرچم shuffle QUEUE_UPDATE MessageType استفاده کنید. برای اطلاعات بیشتر به QueueUpdateRequestData مراجعه کنید.

حالت تکرار

برای اینکه موارد موجود در صف خود را تکرار کنید، ویژگی repeatMode QueueData را هنگام بارگیری موارد در صف، روی RepeatMode مورد نظر قرار دهید.

برای تغییر RepeatMode یک صف موجود، از ویژگی repeatMode QueueUpdateRequestData استفاده کنید که از QUEUE_UPDATE MessageType استفاده می کند.