قائمة المحتوى التالي

نظرة عامة

تتيح حزمة تطوير البرامج (SDK) الخاصة بمستقبل الويب وضع المحتوى في قائمة انتظار مع قائمة الانتظار التلقائية التي تقدّمها حزمة تطوير البرامج (SDK) باستخدام QueueData و QueueManager أو استخدام قائمة انتظار مخصّصة من خلال تطبيق cast.framework.QueueBase واستخدام QueueManager للتحديثات.

تسمح واجهة برمجة تطبيقات "قائمة الانتظار" للتطبيقات بالتكامل بشكل أفضل مع الإرسال من خلال توفير الميزات التالية:

• دعم تنفيذ قائمة انتظار السحابة الإلكترونية من Google والشريك، بحيث يمكن تحميل قائمة الانتظار المخزنة والمنشأة خارجيًا مباشرةً في أجهزة البث.
• الآليات التي تسمح بتقسيم العناصر على قائمة انتظار بدلاً من تحميل كل شيء في وقت واحد.
• دعم للرسائل الجديدة مثل الانتقال إلى العنصر التالي، والعنصر السابق، وجلب نافذة من العناصر، بالإضافة إلى الحصول على معلومات الوسائط المتعلقة بمجموعة من عناصر اللائحة.
• الرمز QueueManager لإدارة إدراج العناصر في قائمة الانتظار وإزالتها وتعديلها.

قائمة الانتظار التلقائية

توفر SDK لمتلقي الويب دعمًا محدودًا في قائمة الانتظار بشكل فوري على شكل قائمة انتظار افتراضية.

لاستخدام قائمة الانتظار التلقائية، يُرجى تقديم queueData في LoadRequestData من التحميلات من جانب المُرسِل أو إرسال طلب تحميل محلي باستخدام PlayerManager#load. راجع أيضًا تحميل الوسائط.

على جانب المستلِم، يمكن تعديل قائمة الانتظار باستخدام QueueManager بعد تحميل الوسائط الأولية.

قائمة الانتظار المخصصة

إذا كانت قائمة الانتظار الافتراضية لا توفر وظائف اللائحة المطلوبة لتطبيقك، فإن إمكانية إنشاء قائمة انتظار مخصصة متوفرة مما يتيح المزيد من الإمكانيات والمرونة.

يمكن لمطوّري التطبيقات إنشاء قائمة انتظار على جانب مستلِم الويب من خلال تنفيذ cast.framework.QueueBase.

في ما يلي مثال بسيط على قائمة انتظار بسيطة يتم من خلالها إلغاء initialize الاستدعاء، ثم يتم تقديم قائمة بعناصر قائمة الانتظار مع أوصافها في قائمة الانتظار إلى جهاز البث.

راجع أيضًا تحميل الوسائط.

// 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. ومع ذلك، بالنسبة إلى تنفيذ قائمة انتظار السحابة الإلكترونية، يمكن لمنطق مستلم الويب المخصص جلب العناصر خارجيًا ثم عرضها كجزء من طلب التهيئة.

لشرح استخدام أكثر شمولاً لواجهة برمجة تطبيقات وضع اللائحة، إليك قائمة تشغيل تجريبية تضم معظم الصف 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 مستقبل المستلم:

رسالة واردة	المعلّمات	رسالة الرد الصادرة	العودة
التالي	لا توجد معلمة مطلوبة.	MEDIA_STATUS	سيعمل المستلِم على (الجلب من خلال العناصر التالية() إذا لزم الأمر) وبدء تشغيل العنصر التالي.
السابق	لا توجد معلمة مطلوبة.	MEDIA_STATUS	سيعمل (مستقبل الويب) (يجلب (prevItems() إذا لزم الأمر) ويبدأ تشغيل العنصر السابق.
FETCH_ITEMS	FetchItemsRequestData	QUEUE_CHANGE	A 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 لعرض قائمة مرتبة عشوائيًا من العناصر.

لترتيب قائمة انتظار حالية بترتيب عشوائي، استخدِم علامة shuffle لعلامة QUEUE_UPDATE MessageType، بدلاً من الأمر QUEUE_SHUFFLE. لمزيد من المعلومات، يُرجى الاطّلاع على QueueUpdateRequestData.

وضع التكرار

لضبط تكرار العناصر في قائمة المحتوى التالي، اضبط السمة repeatMode على السمة QueueData على العنصر المطلوب RepeatMode عند تحميل السلع في قائمة الانتظار.

لتغيير RepeatMode في قائمة انتظار حالية، استخدِم الخاصية repeatMode في QueueUpdateRequestData، والتي تستخدم QUEUE_UPDATE MessageType.