Ü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.
QueueManagerzum 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.