Migrer vers le récepteur Web

Ce guide explique comment migrer une application Cast Receiver v2 vers la dernière application Web Receiver.

Le nouveau SDK CAF (Cast Application Framework, également connu sous le nom de Web Récepteur v3) est une mise à niveau majeure du SDK Récepteur v2. Le SDK Récepteur Web fournit un SDK simple et simplifié pour développer des applications multimédias Web Récepteur.

Web Receiver fournit une API plus cohérente avec les nouvelles API d'expéditeur CAF. Il offre une intégration complète d'un lecteur (MPL et Shaka), ainsi qu'une implémentation et une compatibilité complètes avec les commandes vocales Cast Media et l'Assistant Google. Le SDK CAF fournit également une interface utilisateur par défaut qui peut être facilement stylisée à l'aide de CSS, ainsi qu'un service de liaison de données pour simplifier l'implémentation de l'UI.

Pourquoi migrer ?

En migrant une application Récepteur v2 vers Web Receiver, il est possible d'éliminer une grande partie du code qui traite du lecteur. Vous pouvez ainsi vous concentrer sur l'écriture de la logique métier spécifique à l'application.

CAF intègre parfaitement les lecteurs MPL et Shaka pour étendre la gamme des types de contenus, y compris les types de contenus HTTP Live Streaming (TS et CMAF), MPEG-DASH et Smooth Streaming, ainsi que les types compatibles avec la propriété source Media Element (MP3, MP4, Icecast, etc.). Pour obtenir la liste complète, consultez Supports compatibles avec Google Cast. Actuellement, CAF n'est pas compatible avec un lecteur fourni par l'utilisateur.

La migration vers la CAF permet désormais d'utiliser les commandes vocales avec l'Assistant Google. Toute nouvelle commande vocale avec l'Assistant Google sera automatiquement compatible avec CAF.

En plus d'accepter de nouvelles commandes multimédias, telles que "Modifier les titres par langue" et "Modifier la vitesse de lecture", CAF fournit également une meilleure mise en file d'attente, une assistance intégrée pour les annonces et une meilleure assistance en direct.

Nouveautés

L'API Web Receiver tente de suivre les conventions introduites par les expéditeurs de CAF pour Android et iOS, et elle est assez différente de la version 2.

Le récepteur Web utilise un nouvel espace de noms cast.framework au lieu de cast.receiver pour toutes les API exposées. Un grand nombre d'objets de données utilisés par la version 2 sont identiques dans CAF et sont exposés sous l'espace de noms cast.framework.messages (ils étaient principalement sous cast.receiver.media).

Les services de la version 2 suivants sont remplacés par les services CAF correspondants:

  • La classe CastReceiverManager est remplacée par CastReceiverContext, un singleton qui gère la session Cast, les expéditeurs, l'envoi de messages personnalisés et les événements système globaux. L'interface CastReceiverOptions permet de fournir des options d'application globales (telles que la file d'attente, la version du récepteur, la configuration de lecture, etc.) au contexte.
  • La classe MediaManager est remplacée par PlayerManager, une propriété du singleton CastReceiverContext, qui gère la session multimédia, les requêtes multimédias, les requêtes vocales de l'Assistant Google (CommandAndControlManager dans la version 2) et déclenche des événements multimédias. La configuration des lecteurs (cast.player.api.Host en MPL) est assurée par PlaybackConfig, qui peut être fournie globalement ou par requête de chargement.

PlayerManager expose également les nouvelles classes de sous-gestionnaire:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Logique métier du récepteur

Les gestionnaires d'événements exposés de la réception v2 (tels que CastReceiverManager.onReady ou MediaManager.onLoad) permettent d'ajouter une logique métier. Dans CAF, les gestionnaires d'événements sont remplacés par des écouteurs d'événements (CastReceiverContext.addEventListener) et des intercepteurs de messages (PlayerManager.setMessageInterceptor). Web Receiver peut avoir plusieurs écouteurs d'événements pour un événement (l'écouteur n'affecte pas l'événement) et un intercepteur par message. L'intercepteur peut mettre à jour la requête ou la gérer (renvoyer une requête modifiée, un message de réussite ou un message d'erreur) et peut être un gestionnaire asynchrone qui renvoie une promesse.

L'intercepteur de requêtes de chargement est l'endroit le plus courant pour ajouter une logique spécifique à l'application. Pour les requêtes de chargement d'un expéditeur, l'intercepteur de charge peut convertir l'ID de contenu en URL de contenu. L'intercepteur de charge est également appelé pour les requêtes de préchargement et de préchargement si aucun intercepteur explicite n'a été fourni.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

La version 2 du gestionnaire d'état des supports personnalisés est également remplacée par un intercepteur de messages pour le message d'état multimédia. Les applications de récepteur Web qui ne souhaitent pas exposer l'URL multimédia dans l'état du média peuvent fournir un résolveur d'URL (PlayerManager.setMediaUrlResolver), qui fournit l'URL multimédia pour une requête de chargement. Cette URL est utilisée par la CAF en interne et n'est pas fournie dans l'état du contenu multimédia.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Événements

Web Receiver fournit un large éventail d'événements, à la fois de CastReceiverContext et de PlayerManager. Les applications Récepteur Web peuvent avoir plusieurs écouteurs sur un événement et peuvent également fournir un écouteur à plusieurs événements. (Consultez cast.framework.events.category pour certains groupes d'événements.)

Les événements couvrent toutes les requêtes utilisateur, la progression de la lecture, le traitement du lecteur et tout événement d'élément multimédia de bas niveau (CAF n'expose pas l'élément multimédia lui-même).

L'application de récepteur Web peut ajouter des écouteurs d'événements pour effectuer des actions (par exemple, ajouter une définition de pistes textuelles une fois le chargement terminé) ou effectuer des analyses.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Bus de messages personnalisés

CAF n'expose pas le bus de messages dans l'API. Au lieu de cela, il fournit CastReceiverContext.addCustomMessageListener pour ajouter un écouteur de message pour un espace de noms spécifique (un seul espace de noms) et CastReceiverContext.sendCustomMessage pour envoyer un message sur un espace de noms. Tous les espaces de noms doivent être déclarés avant de démarrer le récepteur Web (c'est-à-dire avant d'appeler CastReceiverContext.start). Les espaces de noms peuvent être déclarés en leur ajoutant un écouteur de message ou peuvent être fournis en tant qu'option de démarrage dans CastReceiverOptions.customNamespaces.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

UI par défaut

CAF fournit une UI de récepteur Web par défaut qui affiche une barre de progression de la lecture et des métadonnées multimédias si nécessaire. L'interface utilisateur par défaut est fournie en tant qu'élément personnalisé (<cast-media-player>) qui peut être stylisé de manière CSS.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Pour une personnalisation plus poussée, une application Web Receiver peut implémenter sa propre interface utilisateur. Web Receiver fournit la classe cast.framework.ui.PlayerDataBinder permettant de lier un objet UI à l'état de lecture du récepteur Web.