Descripción general
El SDK de Web Receiver admite la cola con la cola predeterminada que proporciona el SDK mediante QueueData y QueueManager o una cola personalizada mediante la implementación de cast.framework.QueueBase y el uso de QueueManager para actualizaciones.
La API de Queueing permite que las aplicaciones se integren mejor con Cast proporcionando las siguientes características:
- Asistencia para la implementación de la cola de nube de Google y del socio a fin de que la cola creada y almacenada de forma externa se pueda cargar directamente en los dispositivos de transmisión.
- Mecanismos que permiten la paginación de los elementos en la cola en lugar de cargar todo a la vez.
- Compatibilidad con mensajes nuevos, como ir al siguiente elemento, el elemento anterior, recuperar una ventana de elementos y obtener información multimedia relacionada con un conjunto de elementos de cola.
- El
QueueManagerpara administrar la inserción, eliminación y actualización de los elementos en cola.
Cola predeterminada
El SDK de receptor web proporciona compatibilidad limitada con la cola lista para usar en forma de cola predeterminada.
Para usar la cola predeterminada, proporciona el queueData en el LoadRequestData de las cargas del remitente o envía una solicitud de carga local mediante PlayerManager#load.
Consulta también Cómo cargar contenido multimedia.
En el lado del receptor, la cola se puede modificar mediante el QueueManager una vez que se carga el contenido multimedia inicial.
Cola personalizada
Si la cola predeterminada no proporciona la función de colas que requiere tu app, está disponible la capacidad de crear una cola personalizada, lo que brinda más capacidades y flexibilidad.
Los desarrolladores de aplicaciones pueden crear una cola lateral de receptor web mediante la implementación de cast.framework.QueueBase.
A continuación, se muestra un ejemplo básico de una cola simple en la que se anula la llamada a initialize y, luego, se proporciona una lista de elementos en cola junto con las descripciones de las colas al dispositivo de transmisión.
Consulta también Cómo cargar contenido multimedia.
// 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;
}
};
En este ejemplo, se proporciona la lista de elementos en la llamada initialize en la llamada del constructor QueueBase del proveedor. Sin embargo, para una implementación de colas de Cloud, la lógica del receptor web personalizado puede recuperar los elementos externamente y, luego, mostrarlos como parte de la llamada de inicialización.
Para demostrar un uso más completo de la API de colas, aquí se muestra una cola de demostración que implementa la mayor parte de la clase 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);
}
};
En el ejemplo anterior, YourServer es tu servidor de colas de Cloud y tiene lógica para recuperar ciertos elementos multimedia.
Para usar una cola implementada con QueueBase, uno configuraría la opción de cola en CastReceiverContext:
const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});
Administrar una cola
QueueManager brinda a los desarrolladores flexibilidad para desarrollar sus soluciones de colas. Para ello, proporciona métodos a fin de acceder a la lista de elementos almacenados en cola actualmente almacenada y al elemento de reproducción actual. También proporciona operaciones como la inserción, la eliminación y la actualización de elementos en cola. En el siguiente fragmento, se muestra cómo acceder a una instancia de QueueManager:
const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();
Administración de colas predeterminada
Una vez que se cargó la cola inicial, se puede usar QueueManager para realizar acciones como recuperar el elemento actual, recuperar todos los elementos de la cola y actualizar los elementos en la cola con insertItems, removeItems y updateItems.
Administración de colas personalizada
El siguiente es un ejemplo de una implementación de cola personalizada que usa los métodos de inserción y eliminación basados en algún evento. En el ejemplo, también se muestra el uso de updateItems en el que los desarrolladores pueden modificar los elementos en la cola existente, como la eliminación de las pausas publicitarias.
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;
}));
}
};
Mensajes entrantes y salientes
Para admitir por completo la recuperación de colas del receptor como fuente de información, el SDK del receptor de CAF introduce y maneja los siguientes mensajes de cola adicionales:
| Mensaje entrante | Parámetros | Mensaje de respuesta saliente | Volver |
| SIGUIENTE | No se necesita ningún parámetro. | MEDIA_STATUS | El receptor hará una recuperación (si es necesario, mediante nextItems()) y comenzará a reproducir el siguiente elemento. |
| ANTERIOR | No se necesita ningún parámetro. | MEDIA_STATUS | El receptor web (recuperará mediante prevItems() si es necesario) y comenzará a reproducir el elemento anterior. |
| FETCH_ITEMS | FetchItemsRequestData | QUEUE_CHANGE | Un cast.framework.messages.QueueChange. Por ejemplo, para un caso de inserción, el campo de elementos en el JSON contendrá la lista de los elementos nuevos recuperados. |
| GET_ITEMS_INFO. | GetItemsInfoRequestData que contiene itemIds: Arreglo<number> | ITEMS_INFO | cast.framework.messages.ItemsInfo con información del elemento en cola. |
| GET_QUEUE_IDS. | No se necesita ningún parámetro. | QUEUE_IDS | cast.framework.messages.QueueIds. |
Para NEXT/PREVIOUS, si la representación de cola existente en el receptor web no tiene más elementos, se invoca de forma automática a QueueBase.nextItems() o a QueueBase.prevItems() para recibir más elementos.
En FETCH_ITEM, se llama a la función correspondiente fetchItems en la implementación de QueueBase para las colas de Cloud, que recupera los datos relevantes que se muestran al receptor web a fin de almacenarlos.
Cada vez que se recuperan más elementos, se activa un nuevo tipo de mensaje QUEUE_CHANGE y se envía de nuevo al remitente. Consulta los distintos tipos de cambios en las colas.
Para GET_ITEMS_INFO, no se activa la implementación de QueueBase, y el receptor web muestra información multimedia ya conocida en la lista de ID.
Arrastrar aleatoriamente una cola
Para configurar los elementos en la cola que se mezclarán, establece la marca shuffle de QueueData en true cuando cargues los elementos en la cola.
Si usas una implementación de QueueBase, usa el método shuffle para mostrar una lista aleatoria de elementos.
Para redistribuir una cola existente, usa la marca shuffle del MessageType QUEUE_UPDATE, en lugar del comando QUEUE_SHUFFLE. Consulta QueueUpdateRequestData para obtener más información.
Modo de repetición
Para configurar la repetición de los elementos en tu cola, configura la propiedad repeatMode de QueueData con el RepeatMode deseado cuando cargues los elementos en la cola.
Para cambiar la RepeatMode de una cola existente, usa la propiedad repeatMode de QueueUpdateRequestData, que usa QUEUE_UPDATE MessageType.