نمای کلی
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
استفاده می کند.