Übersicht
Das Web Receiver SDK unterstützt Warteschlangen mit der Standardwarteschlange, die vom SDK mit QueueData
und QueueManager
bereitgestellt wird. Sie können auch eine benutzerdefinierte Warteschlange verwenden, indem Sie cast.framework.QueueBase
implementieren und QueueManager
für Aktualisierungen verwenden.
Die Queueing API ermöglicht die optimale Einbindung von Anwendungen in Cast durch die Bereitstellung folgender Funktionen:
- Unterstützung der Cloud-Warteschlangenimplementierung von Google und Partnern, sodass extern gespeicherte und erstellte Warteschlangen direkt in Cast-Geräte geladen werden können.
- Mechanismen, die die Paginierung von Elementen in der Warteschlange ermöglichen, statt alles auf einmal zu laden.
- Unterstützung neuer Nachrichten, z. B. zum nächsten Element, zum vorherigen Element, zum Abrufen eines Fensters mit Elementen sowie zum Abrufen von Medieninformationen in Bezug auf eine Reihe von Warteschlangenelementen.
QueueManager
zum Verwalten des Einfügens, Entfernens und Aktualisierens von Warteschlangenelementen.
Standardwarteschlange
Das Web Receiver SDK bietet eine begrenzte Warteschlangenunterstützung in Form einer Standardwarteschlange.
Wenn Sie die Standardwarteschlange verwenden möchten, geben Sie queueData
in der Datei LoadRequestData
der Absenderlast an oder senden Sie eine lokale Ladeanfrage mit PlayerManager#load
.
Weitere Informationen finden Sie unter Medien laden.
Auf Empfängerseite kann die Warteschlange mithilfe von QueueManager
geändert werden, nachdem das anfängliche Medium geladen wurde.
Benutzerdefinierte Warteschlange
Wenn die Standardwarteschlange nicht die Warteschlangenfunktion bietet, die für Ihre Anwendung erforderlich ist, können Sie benutzerdefinierte Warteschlangen erstellen, um mehr Funktionen und Flexibilität zu erhalten.
Anwendungsentwickler können durch Implementieren von cast.framework.QueueBase
eine Web Receiver-Seite in der Empfängerliste erstellen.
Hier ist ein einfaches Beispiel für eine einfache Warteschlange, in der der initialize
-Aufruf überschrieben wird. Anschließend werden dem Übertragungsgerät eine Liste von Warteschlangenelementen sowie Warteschlangenbeschreibungen zur Verfügung gestellt.
Weitere Informationen finden Sie unter Medien laden.
// 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;
}
};
In diesem Beispiel finden Sie die Liste der Elemente im initialize
-Aufruf im Konstruktoraufruf QueueBase
des Anbieters. Bei einer Cloud-Warteschlangenimplementierung kann die benutzerdefinierte Logik des Webempfängers die Elemente jedoch extern abrufen und dann als Teil des Initialisierungsaufrufs zurückgeben.
Im Folgenden finden Sie eine Demo-Warteschlange, in der ein Großteil der QueueBase
-Klasse implementiert wird. So lässt sich die umfassendere Verwendung der Queueing API demonstrieren.
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);
}
};
Im Beispiel oben ist YourServer
Ihr Cloud-Warteschlangenserver und hat eine Logik zum Abrufen bestimmter Medienelemente.
Wenn Sie die in die Warteschlange von QueueBase
implementierte Warteschlange verwenden möchten, legen Sie die Warteschlangenoption in CastReceiverContext
fest:
const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});
Warteschlange verwalten
Mit QueueManager
können Entwickler ihre Warteschlangenlösungen flexibel entwickeln. Dabei werden Methoden bereitgestellt, um auf die aktuell gespeicherte Liste von Warteschlangenelementen sowie auf das aktuell wiedergegebene Element zuzugreifen. Außerdem können darin Elemente in die Warteschlange gestellt, entfernt oder aktualisiert werden. Das folgende Snippet zeigt, wie Sie auf eine Instanz von QueueManager
zugreifen können:
const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();
Standardwarteschlangenverwaltung
Nachdem die anfängliche Warteschlange geladen wurde, können mit QueueManager
Aktionen wie das Abrufen des aktuellen Elements, das Abrufen aller Elemente in der Warteschlange und das Aktualisieren der Elemente in der Warteschlange mit insertItems
, removeItems
und updateItems
ausgeführt werden.
Benutzerdefinierte Warteschlangenverwaltung
Im Folgenden finden Sie ein Beispiel für eine Implementierung einer benutzerdefinierten Warteschlange, in der die Methoden zum Einfügen und Entfernen basierend auf einem Ereignis verwendet werden. Das Beispiel zeigt auch die Verwendung von updateItems
, bei der die Entwickler die Warteschlangenelemente in der vorhandenen Warteschlange ändern können, z. B. Werbeunterbrechungen entfernen.
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;
}));
}
};
Eingehende und ausgehende Nachrichten
Damit das Abrufen aus der Empfängerseite in vollem Umfang als "Source of Truth" unterstützt wird, werden die folgenden zusätzlichen Warteschlangennachrichten vom CAF Receiver SDK eingeführt und verarbeitet:
Eingehende Nachricht | Parameter | Antwort auf ausgehende Nachrichten | Rückgabe |
WEITER | Kein Parameter erforderlich. | MEDIA_STATUS | Der Empfänger ruft (bei Bedarf über nextItems()) ab und beginnt mit der Wiedergabe des nächsten Elements. |
VORHERIGES | Kein Parameter erforderlich. | MEDIA_STATUS | Der Web Receiver ruft (bei Bedarf über prevItems()) ab und startet das vorherige Element. |
FETCH_ELEMENTE | FetchItemsRequestData | QUEUE_ÄNDERUNG | Ein cast.framework.messages.QueueChange. Für einen Einfügungsfall enthält das Feld „items“ im JSON-Code beispielsweise die Liste der abgerufenen neuen Elemente. |
GET_ITEMS_INFO | GetItemsInfoRequestData mit itemIds: Array<number> | ARTIKEL_INFO | cast.framework.messages.ItemsInfo mit Informationen zur Warteschlange. |
GET_QUEUE_IDS | Kein Parameter erforderlich. | QUEUE_IDS | cast.framework.messages.QueueIds verwendet wird. |
Wenn für NEXT
/PREVIOUS
keine vorhandene Elemente in der vorhandenen Warteschlangendarstellung vorhanden sind, wird QueueBase.nextItems()
oder QueueBase.prevItems()
automatisch aufgerufen, um weitere Elemente zu empfangen.
Für FETCH_ITEM
wird die entsprechende Funktion fetchItems
in der QueueBase
-Implementierung für Cloud-Warteschlangen aufgerufen, die die relevanten Daten abrufen, die an den Webempfänger zum Speichern zurückgegeben werden.
Wenn weitere Elemente abgerufen werden, wird ein neuer Nachrichtentyp QUEUE_CHANGE
ausgelöst und an den Absender zurückgesendet. Siehe die verschiedenen Arten von Warteschlangenänderungen.
Bei GET_ITEMS_INFO
wird die Implementierung von QueueBase
nicht ausgelöst und der Webempfänger gibt Medieninformationen zurück, die der Liste der IDs bereits bekannt sind.
Zufallsmix einer Warteschlange
Wenn Sie möchten, dass die Elemente in der Warteschlange als Zufallsmix festgelegt werden, setzen Sie das Flag shuffle
von QueueData
auf true
, wenn die Elemente in die Warteschlange geladen werden.
Wenn Sie eine Implementierung von QueueBase
verwenden, verwenden Sie die Methode shuffle
, um eine zufällig angeordnete Liste von Elementen zurückzugeben.
Verwenden Sie zum Zufallsmix einer Warteschlange das Flag shuffle
von QUEUE_UPDATE
MessageType
anstelle des Befehls QUEUE_SHUFFLE
. Weitere Informationen finden Sie unter QueueUpdateRequestData
.
Wiederholungsmodus
Wenn die Elemente in der Warteschlange wiederholt werden sollen, legen Sie beim Laden der Elemente in der Warteschlange das Attribut repeatMode
von QueueData
auf die gewünschte RepeatMode
fest.
Zum Ändern des RepeatMode
einer vorhandenen Warteschlange verwenden Sie das Attribut repeatMode
von QueueUpdateRequestData
, das die QUEUE_UPDATE
MessageType
verwendet.