Intégrer le SDK Cast à votre application d'envoi Web

Ce guide du développeur explique comment ajouter la compatibilité avec Google Cast à votre application Web Sender à l'aide du SDK Cast.

Terminologie

L'appareil mobile ou le navigateur est l'émetteur, qui contrôle la lecture. L'appareil Google Cast est le récepteur, qui affiche le contenu à l'écran pour la lecture.

Le SDK Web Sender se compose de deux parties : l'API Framework (cast.framework) et l'API Base (chrome.cast) En général, vous effectuez des appels sur l'API Framework de niveau supérieur plus simple, qui sont ensuite traités par l'API Base de niveau inférieur.

Le framework de l'émetteur fait référence à l'API Framework, au module et aux ressources associées qui fournissent un wrapper autour des fonctionnalités de niveau inférieur. L'application émettrice ou l'application Google Cast Chrome fait référence à une application Web (HTML/JavaScript) s'exécutant dans un navigateur Chrome sur un appareil émetteur. Une application Web Receiver fait référence à une application HTML/JavaScript s'exécutant sur Chromecast ou un appareil Cast.

Le framework de l'émetteur utilise une conception de rappel asynchrone pour informer l'application émettrice des événements et passer d'un état à l'autre du cycle de vie de l'application Cast.

Charger la bibliothèque

Pour que votre application implémente les fonctionnalités de Google Cast, elle doit connaître l'emplacement du SDK Google Cast Web Sender, comme indiqué ci-dessous. Ajoutez le paramètre de requête d'URL loadCastFramework pour charger également l'API Web Sender Framework. Toutes les pages de votre application doivent faire référence à la bibliothèque comme suit :

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Framework

Le SDK Web Sender utilise l'espace de noms cast.framework.* . L'espace de noms représente les éléments suivants :

  • Méthodes ou fonctions qui appellent des opérations sur l'API
  • Écouteurs d'événements pour les fonctions d'écouteur dans l'API

Le framework se compose des principaux composants suivants :

  • Le CastContext est un objet singleton qui fournit des informations sur l' état Cast actuel et déclenche des événements pour les changements d'état Cast et de session Cast.
  • L'objet CastSession gère la session. Il fournit des informations sur l'état et déclenche des événements, tels que les modifications du volume de l'appareil, de l'état de mise en sourdine et des métadonnées de l'application.
  • L'élément de bouton Cast, qui est un simple élément HTML personnalisé qui étend le bouton HTML. Si le bouton Cast fourni ne suffit pas, vous pouvez utiliser l'état Cast pour implémenter un bouton Cast.
  • Le RemotePlayerController fournit la liaison de données pour simplifier l'implémentation du lecteur à distance.

Consultez la documentation de référence de l'API Google Cast Web Sender pour obtenir une description complète de l'espace de noms.

Icône Cast

Le composant de bouton Cast de votre application est entièrement géré par le framework. Cela inclut la gestion de la visibilité, ainsi que la gestion des événements de clic.

<google-cast-launcher></google-cast-launcher>

Vous pouvez également créer le bouton par programmation :

document.createElement("google-cast-launcher");

Vous pouvez appliquer n'importe quel style supplémentaire, tel que la taille ou le positionnement, à l'élément si nécessaire. Utilisez l'attribut --connected-color pour choisir la couleur de l'état connecté de Web Receiver et --disconnected-color pour l'état déconnecté.

Initialisation

Après avoir chargé l'API Framework, l'application appelle le gestionnaire window.__onGCastApiAvailable. Vous devez vous assurer que l'application définit ce gestionnaire sur le window avant de charger la bibliothèque de l'émetteur.

Dans ce gestionnaire, vous initialisez l'interaction Cast en appelant la setOptions(options) méthode de CastContext.

Exemple :

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

Ensuite, initialisez l'API comme suit :

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

Tout d'abord, l'application récupère l'instance singleton de l' CastContext objet fournie par le framework. Elle utilise ensuite setOptions(options) avec un CastOptions objet pour définir le applicationID.

Si vous utilisez le récepteur média par défaut, qui ne nécessite pas d'enregistrement, utilisez une constante prédéfinie par le SDK Web Sender, comme indiqué ci-dessous, au lieu de l'applicationID :

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

Commande multimédia

Une fois que CastContext a été initialisé, l'application peut récupérer le CastSession actuel à tout moment à l'aide de getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

Le CastSession peut être utilisé pour charger des contenus multimédias sur l'appareil Cast connecté à l'aide de loadMedia(loadRequest). Commencez par créer un MediaInfo, en utilisant le contentId et le contentType, ainsi que toute autre information liée au contenu. Créez ensuite un LoadRequest à partir de celui-ci, en définissant toutes les informations pertinentes pour la requête. Enfin, appelez loadMedia(loadRequest) sur votre CastSession.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

La méthode loadMedia renvoie une promesse qui peut être utilisée pour effectuer toutes les opérations nécessaires à un résultat positif. Si la promesse est rejetée, l'argument de la fonction sera un chrome.cast.ErrorCode.

Vous pouvez accéder aux variables d'état du lecteur dans RemotePlayer. Toutes les interactions avec le RemotePlayer, y compris les rappels et les commandes d'événements multimédias, sont gérées avec le RemotePlayerController.

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

RemotePlayerController offre à l'application un contrôle multimédia complet des commandes LECTURE, PAUSE, ARRÊT et RECHERCHE pour le contenu multimédia chargé.

  • LECTURE/PAUSE : playerController.playOrPause();
  • ARRÊT : playerController.stop();
  • RECHERCHE : playerController.seek();

Les RemotePlayer et RemotePlayerController peuvent être utilisés avec des frameworks de liaison de données, tels que Polymer ou Angular, pour implémenter un lecteur à distance.

Voici un extrait de code pour Angular :

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

État du fichier multimédia

Pendant la lecture de contenus multimédias, différents événements se produisent. Vous pouvez les capturer en définissant des écouteurs pour différents cast.framework.RemotePlayerEventType événements sur l' RemotePlayerControllerobjet.

Pour obtenir les informations sur l'état du contenu multimédia, utilisez l' cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED événement, qui se déclenche lorsque la lecture change et lorsque le CastSession.getMediaSession().media change.

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

Lorsque des événements tels que la pause, la lecture, la reprise ou la recherche se produisent, l'application doit agir en conséquence et se synchroniser avec l'application Web Receiver sur l'appareil Cast. Pour en savoir plus, consultez Mises à jour de l'état.

Fonctionnement de la gestion des sessions

Le SDK Cast introduit le concept de session Cast, dont l'établissement combine les étapes de connexion à un appareil, de lancement (ou de reprise) d'une application Web Receiver, de connexion à cette application et d'initialisation d'un canal de commande multimédia. Pour en savoir plus sur les sessions Cast et le cycle de vie de Web Receiver, consultez le guide sur le cycle de vie de l'application Web Receiver .

Les sessions sont gérées par la classe CastContext, que votre application peut récupérer via cast.framework.CastContext.getInstance(). Les sessions individuelles sont représentées par des sous-classes de la classe Session. Par exemple, CastSession représente les sessions avec des appareils Cast. Votre application peut accéder à la session Cast actuellement active via CastContext.getCurrentSession().

Pour surveiller l'état de la session, ajoutez un écouteur au CastContext pour le CastContextEventType.SESSION_STATE_CHANGED type d'événement.

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

Pour la déconnexion, par exemple lorsque l'utilisateur clique sur le bouton "Arrêter la diffusion" dans la boîte de dialogue Cast, vous pouvez ajouter un écouteur pour le RemotePlayerEventType.IS_CONNECTED_CHANGED type d'événement dans votre écouteur. Dans votre écouteur, vérifiez si RemotePlayer est déconnecté. Si c'est le cas, mettez à jour l'état du lecteur local si nécessaire. Exemple :

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

Bien que l'utilisateur puisse contrôler directement l'arrêt de la diffusion via le bouton Cast du framework, l'émetteur lui-même peut arrêter la diffusion à l'aide de l'objet CastSession actuel.

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

Transfert de diffusion

La préservation de l'état de la session est la base du transfert de diffusion, où les utilisateurs peuvent déplacer des flux audio et vidéo existants entre les appareils à l'aide de commandes vocales, de l'application Google Home ou d'écrans connectés. Le contenu multimédia cesse d'être lu sur un appareil (la source) et continue sur un autre (la destination). Tout appareil Cast doté du dernier micrologiciel peut servir de source ou de destination lors d'un transfert de diffusion.

Pour obtenir le nouvel appareil de destination lors du transfert de diffusion, appelez CastSession#getCastDevice() lorsque l'événement cast.framework.SessionState.SESSION_RESUMED est appelé.

Pour en savoir plus, consultez Transfert de diffusion sur Web Receiver.

Précédent
Configuration
Suivant
Ajouter des fonctionnalités avancées