Présentation
Le SDK Récepteur Web accepte la mise en file d'attente avec la file d'attente par défaut fournie par le SDK à l'aide de QueueData
et QueueManager
, ou d'une file d'attente personnalisée en implémentant cast.framework.QueueBase
et en utilisant QueueManager
pour les mises à jour.
L'API Queueing facilite l'intégration des applications à Cast en offrant les fonctionnalités suivantes:
- Prise en charge de l'implémentation de la file d'attente cloud de Google et de son partenaire, permettant de charger directement la file d'attente stockée et créée en externe dans les appareils Cast
- Mécanismes permettant la pagination des éléments de la file d'attente plutôt que de tout charger en même temps
- Prise en charge de nouveaux messages, tels que l'accès à l'élément suivant, l'élément précédent, l'extraction d'une fenêtre d'éléments et l'obtention d'informations multimédias liées à un ensemble d'éléments de file d'attente.
- La méthode
QueueManager
pour gérer l'insertion, la suppression et la mise à jour des éléments de la file d'attente
File d'attente par défaut
Le SDK Récepteur Web fournit une compatibilité de file d'attente limitée sous la forme d'une file d'attente par défaut.
Pour utiliser la file d'attente par défaut, fournissez l'identifiant queueData
dans le fichier LoadRequestData
de vos chargements côté expéditeur ou envoyez une requête de chargement locale à l'aide de PlayerManager#load
.
Consultez également Chargement des contenus multimédias.
Côté destinataire, la file d'attente peut être modifiée à l'aide de QueueManager
une fois le support initial chargé.
File d'attente personnalisée
Si la file d'attente par défaut ne fournit pas la fonctionnalité de mise en file d'attente requise pour votre application, la possibilité de créer une file d'attente personnalisée est disponible, ce qui offre davantage de capacités et de flexibilité.
Les développeurs d'applications peuvent créer une file d'attente latérale de récepteur Web en implémentant cast.framework.QueueBase
.
Voici un exemple de base de file d'attente simple où l'appel initialize
est remplacé, puis une liste des éléments de la file d'attente et des descriptions de la file d'attente est fournie à l'appareil Cast.
Consultez également Chargement des contenus multimédias.
// 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;
}
};
Dans cet exemple, la liste des éléments de l'appel initialize
est fournie dans l'appel du constructeur QueueBase
du fournisseur. Toutefois, pour une implémentation de file d'attente cloud, la logique de réception Web personnalisée peut récupérer les éléments en externe, puis les renvoyer dans le cadre de l'appel d'initialisation.
Pour illustrer une utilisation plus complète de l'API de mise en file d'attente, voici une file d'attente de démonstration qui implémente la plupart de la classe 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);
}
};
Dans l'exemple ci-dessus, YourServer
est votre serveur de file d'attente cloud et dispose d'une logique pour récupérer certains éléments multimédias.
Pour utiliser la mise en file d'attente implémentée par QueueBase
, vous devez définir l'option de file d'attente dans CastReceiverContext
:
const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});
Gérer une file d'attente
QueueManager
offre aux développeurs une certaine flexibilité dans le développement de leurs solutions de file d'attente grâce à des méthodes permettant d'accéder à la liste des éléments de la file d'attente et à l'élément en cours de stockage. Elle permet également d'effectuer des opérations telles que l'insertion, la suppression et la mise à jour d'éléments en attente. L'extrait de code suivant montre comment accéder à une instance de QueueManager
:
const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();
Gestion par défaut de la file d'attente
Une fois la file d'attente initiale chargée, vous pouvez utiliser QueueManager
pour effectuer des actions telles que la récupération de l'élément actuel, la récupération de tous les éléments de la file d'attente et la mise à jour des éléments dans la file d'attente à l'aide de insertItems
, removeItems
et updateItems
.
Gestion personnalisée des files d'attente
Voici un exemple d'implémentation de file d'attente personnalisée qui utilise les méthodes d'insertion et de suppression en fonction d'un événement. L'exemple montre également comment updateItems
permet aux développeurs de modifier les éléments de la file d'attente existante, par exemple pour les supprimer.
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;
}));
}
};
Messages entrants et sortants
Pour assurer une compatibilité totale avec la récupération de files d'attente côté destinataire en tant que source fiable, les messages supplémentaires suivants sont introduits et gérés par le SDK CAF Receiver:
Message entrant | Paramètres | Message de réponse sortant | Retour |
SUIVANT | Aucun paramètre requis. | MEDIA_STATUS | Le récepteur (récupère nextItems() si nécessaire) et lance la lecture de l'élément suivant. |
PRÉCÉDENT | Aucun paramètre requis. | MEDIA_STATUS | Le récepteur Web (récupère prevItems() si nécessaire) et lance la lecture de l'élément précédent. |
FETCH_ITEMS | FetchItemsRequestData | CHANGEMENT DE FILE | Un cast.framework.messages.QueueChange Par exemple, dans le cas d'un cas d'insertion, le champ "items" du fichier JSON contient la liste des nouveaux éléments récupérés. |
GET_ITEMS_INFO | GetItemsInfoRequestData contenant itemIds : tableau<number> | INFOS_ARTICLES | cast.framework.messages.ItemsInfo avec les informations de l'élément de file d'attente. |
GET_QUEUE_IDS | Aucun paramètre requis. | ID_DU_QUEUE | cast.framework.messages.QueueIds. |
Pour NEXT
/PREVIOUS
, si la représentation de file d'attente existante sur le récepteur Web ne comporte plus d'éléments, QueueBase.nextItems()
ou QueueBase.prevItems()
est automatiquement appelé pour recevoir plus d'éléments.
Pour FETCH_ITEM
, la fonction correspondante fetchItems
dans l'implémentation de QueueBase
est appelée pour les files d'attente cloud, qui récupère les données pertinentes à renvoyer au récepteur Web pour stockage.
Chaque fois que des éléments sont récupérés, un nouveau type de message QUEUE_CHANGE
est déclenché et renvoyé à l'expéditeur. Consultez les différents types de changements de files d'attente.
Pour GET_ITEMS_INFO
, l'implémentation de QueueBase
n'est pas déclenchée et le récepteur Web renvoie des informations multimédias déjà connues dans la liste d'ID.
Lecture aléatoire d'une file d'attente
Pour que les éléments de votre file d'attente soient brassés, définissez l'option shuffle
de QueueData
sur true
lors du chargement de vos éléments dans la file d'attente.
Si vous utilisez une implémentation de QueueBase
, utilisez la méthode shuffle
pour renvoyer une liste aléatoire d'éléments.
Pour lire une file d'attente existante en mode aléatoire, utilisez l'option shuffle
de l'élément QUEUE_UPDATE
MessageType
, plutôt que la commande QUEUE_SHUFFLE
. Pour en savoir plus, consultez QueueUpdateRequestData
.
Mode de répétition
Pour que les éléments de la file d'attente se répètent, définissez la propriété repeatMode
de QueueData
sur l'élément RepeatMode
souhaité lors du chargement de vos éléments dans la file d'attente.
Pour modifier l'élément RepeatMode
d'une file d'attente existante, utilisez la propriété repeatMode
de l'élément QueueUpdateRequestData
, qui utilise QUEUE_UPDATE
MessageType
.