نظرة عامة
تتيح حزمة تطوير البرامج (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
.