Ajouter des fonctionnalités de base à votre récepteur Web personnalisé

Cette page contient des extraits de code et des descriptions des fonctionnalités disponibles pour une application de réception Web personnalisée.

  1. Un élément cast-media-player qui représente l'UI du lecteur intégré fournie avec Web Receiver.
  2. Un style CSS personnalisé pour l'élément cast-media-player afin d'appliquer un style à divers éléments d'interface utilisateur tels que background-image, splash-image et font-family
  3. Un élément de script pour charger le framework Web Receiver.
  4. le code JavaScript pour intercepter les messages et gérer les événements.
  5. File d'attente pour lecture automatique
  6. Options permettant de configurer la lecture
  7. Options permettant de définir le contexte Web Receiver.
  8. Options permettant de définir les commandes compatibles avec l'application Web Receiver
  9. Un appel JavaScript pour démarrer l'application Web Receiver

Configuration et options de l'application

Configurer l'application

CastReceiverContext est la classe externe exposée au développeur. Elle gère le chargement des bibliothèques sous-jacentes ainsi que l'initialisation du SDK Web Receiver. Le SDK fournit des API qui permettent aux développeurs d'applications de le configurer via CastReceiverOptions. Ces configurations sont évaluées une fois par lancement d'application et sont transmises au SDK lors de la définition du paramètre facultatif dans l'appel de start.

L'exemple ci-dessous montre comment ignorer le comportement par défaut permettant de détecter si une connexion de l'expéditeur est toujours active. Lorsque le récepteur Web n'a pas pu communiquer avec un expéditeur pendant maxInactivity secondes, un événement SENDER_DISCONNECTED est envoyé. La configuration ci-dessous remplace ce délai. Cela peut être utile lors du débogage de problèmes, car cela empêche l'application Web Receiver de fermer la session du débogueur à distance Chrome lorsqu'aucun expéditeur connecté n'est associé à l'état IDLE.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

Configurer le lecteur

Lors du chargement du contenu, le SDK Web Receiver permet de configurer des variables de lecture telles que les informations DRM, les configurations de nouvelles tentatives et les gestionnaires de requêtes à l'aide de cast.framework.PlaybackConfig. Ces informations sont gérées par PlayerManager et évaluées au moment de la création des joueurs. Les lecteurs sont créés chaque fois qu'un nouveau chargement est transmis au SDK Web Receiver. Les modifications apportées à PlaybackConfig après la création du lecteur sont évaluées lors du prochain chargement de contenu. Le SDK fournit les méthodes suivantes pour modifier le PlaybackConfig.

  • CastReceiverOptions.playbackConfig pour remplacer les options de configuration par défaut lors de l'initialisation de CastReceiverContext.
  • PlayerManager.getPlaybackConfig() pour obtenir la configuration actuelle.
  • PlayerManager.setPlaybackConfig() pour remplacer la configuration actuelle. Ce paramètre est appliqué à tous les chargements suivants ou jusqu'à ce qu'il soit à nouveau remplacé.
  • PlayerManager.setMediaPlaybackInfoHandler() pour n'appliquer des configurations supplémentaires qu'à l'élément multimédia en cours de chargement en plus des configurations actuelles. Le gestionnaire est appelé juste avant la création du lecteur. Les modifications apportées ici ne sont pas permanentes et ne sont pas incluses dans les requêtes adressées à getPlaybackConfig(). Lorsque l'élément multimédia suivant est chargé, ce gestionnaire est appelé à nouveau.

L'exemple ci-dessous montre comment définir PlaybackConfig lors de l'initialisation de CastReceiverContext. La configuration remplace les requêtes sortantes d'obtention de fichiers manifestes. Le gestionnaire indique que les requêtes de contrôle d'accès CORS doivent être effectuées à l'aide d'identifiants tels que des cookies ou des en-têtes d'autorisation.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

L'exemple ci-dessous montre comment remplacer PlaybackConfig à l'aide des getter et setter fournis dans PlayerManager. Ce paramètre configure le lecteur pour qu'il reprenne la lecture du contenu après le chargement d'un segment.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

L'exemple ci-dessous montre comment remplacer PlaybackConfig pour une requête de chargement spécifique à l'aide du gestionnaire d'informations de lecture multimédia. Le gestionnaire appelle une méthode getLicenseUrlForMedia implémentée par l'application pour obtenir le licenseUrl à partir du contentId de l'élément actuel.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Écouteur d'événements

Le SDK Web Receiver permet à votre application Web Receiver de gérer les événements du lecteur. L'écouteur d'événements utilise un paramètre cast.framework.events.EventType (ou un tableau de ces paramètres) qui spécifie les événements qui doivent déclencher l'écouteur. Les tableaux préconfigurés de cast.framework.events.EventType qui sont utiles pour le débogage se trouvent dans cast.framework.events.category. Le paramètre d'événement fournit des informations supplémentaires sur l'événement.

Par exemple, si vous souhaitez savoir quand une modification mediaStatus est diffusée, vous pouvez utiliser la logique suivante pour gérer l'événement:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Interception de messages

Le SDK Web Receiver permet à votre application Web Receiver d'intercepter des messages et d'exécuter un code personnalisé sur ces messages. L'intercepteur de messages utilise un paramètre cast.framework.messages.MessageType qui spécifie le type de message à intercepter.

L'intercepteur doit renvoyer la requête modifiée ou une promesse qui se résout avec la valeur de requête modifiée. Le renvoi de null empêche l'appel du gestionnaire de messages par défaut. Pour en savoir plus, consultez la section Chargement de médias.

Par exemple, si vous souhaitez modifier les données de requête de chargement, vous pouvez utiliser la logique suivante pour les intercepter et les modifier:

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

Gestion des exceptions

Lorsque des erreurs se produisent dans l'intercepteur de messages, votre application Récepteur Web doit renvoyer des cast.framework.messages.ErrorType et des cast.framework.messages.ErrorReason appropriés.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

Interception des messages ou écouteur d'événements

Voici quelques différences clés entre l'interception des messages et l'écouteur d'événements:

  • Un écouteur d'événements ne vous permet pas de modifier les données de la requête.
  • Un écouteur d'événements est plus adapté pour déclencher des analyses ou une fonction personnalisée.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • L'interception de messages vous permet d'écouter un message, de l'intercepter et de modifier les données de la requête elles-mêmes.
  • L'interception des messages est particulièrement utile pour gérer la logique personnalisée en ce qui concerne les données de requête.

Chargement de contenu multimédia

MediaInformation fournit de nombreuses propriétés permettant de charger du contenu multimédia dans le message cast.framework.messages.MessageType.LOAD, y compris entity, contentUrl et contentId.

  • entity est la propriété que nous vous recommandons d'utiliser dans votre implémentation pour vos applications émettrices et destinataires. La propriété est une URL de lien profond qui peut être une playlist ou du contenu multimédia. Votre application doit analyser cette URL et renseigner au moins l'un des deux autres champs.
  • L'élément contentUrl correspond à l'URL de lecture que le lecteur utilisera pour charger le contenu. Par exemple, cette URL peut renvoyer vers un fichier manifeste DASH.
  • Le contentId peut être une URL de contenu lisible (semblable à celle de la propriété contentUrl) ou un identifiant unique pour le contenu ou la playlist en cours de chargement. Si vous utilisez cette propriété comme identifiant, votre application doit insérer une URL lisible dans contentUrl.

Nous vous suggérons d'utiliser entity pour stocker l'ID réel ou les paramètres de clé, et contentUrl pour l'URL du contenu multimédia. Un exemple est présenté dans l'extrait de code suivant, où entity est présent dans la requête LOAD et où le contentUrl lisible est récupéré:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

Fonctionnalités de l'appareil

La méthode getDeviceCapabilities fournit des informations sur l'appareil Cast connecté et l'appareil vidéo ou audio qui lui est connecté. La méthode getDeviceCapabilities fournit des informations de prise en charge pour l'Assistant Google, le Bluetooth, et les appareils d'affichage et audio connectés.

Cette méthode renvoie un objet que vous pouvez interroger en transmettant l'une des énumérations spécifiées afin d'obtenir la capacité de l'appareil pour cette énumération. Les énumérations sont définies dans le fichier cast.framework.system.DeviceCapabilities.

Cet exemple vérifie si le récepteur Web est capable de lire des contenus HDR et DolbyVision (DV) à l'aide des touches IS_HDR_SUPPORTED et IS_DV_SUPPORTED, respectivement.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

Gérer les interactions des utilisateurs

Un utilisateur peut interagir avec votre application Web Receiver via des applications émettrices (Web, Android et iOS), des commandes vocales sur les appareils avec Assistant Google intégré, des commandes tactiles sur des écrans connectés et des télécommandes sur les appareils Android TV. Le SDK Cast fournit plusieurs API permettant à l'application Web Receiver de gérer ces interactions, de mettre à jour l'interface utilisateur de l'application via les états d'action de l'utilisateur et, éventuellement, d'envoyer les modifications pour mettre à jour les services de backend.

Commandes multimédias compatibles

Les états des commandes d'interface utilisateur sont déterminés par MediaStatus.supportedMediaCommands pour les manettes agrandies des émetteurs iOS et Android, les applications de réception et de télécommande exécutées sur des appareils tactiles, ainsi que les applications de récepteur sur les appareils Android TV. Lorsqu'une Command au niveau du bit est activée dans la propriété, les boutons associés à cette action le sont également. Si la valeur n'est pas définie, le bouton est désactivé. Ces valeurs peuvent être modifiées sur Web Receiver en:

  1. Utiliser PlayerManager.setSupportedMediaCommands pour définir un Commands spécifique
  2. Ajouter une commande à l'aide de addSupportedMediaCommands
  3. Supprimer une commande existante à l'aide de removeSupportedMediaCommands
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Lorsque le récepteur prépare la MediaStatus mise à jour, il inclut les modifications dans la propriété supportedMediaCommands. Lorsque l'état est diffusé, les applications émettrices connectées mettent à jour les boutons de leur UI en conséquence.

Pour en savoir plus sur les commandes multimédias et les appareils tactiles compatibles, consultez le guide Accessing UI controls.

Gérer les états des actions des utilisateurs

Lorsque les utilisateurs interagissent avec l'interface utilisateur ou envoient des commandes vocales, ils peuvent contrôler la lecture du contenu et les propriétés liés à l'élément en cours de lecture. Les requêtes qui contrôlent la lecture sont gérées automatiquement par le SDK. Les requêtes qui modifient les propriétés de l'élément en cours de lecture, telles qu'une commande LIKE, nécessitent que l'application réceptrice les gère. Le SDK fournit une série d'API pour gérer ces types de requêtes. Pour prendre en charge ces requêtes, vous devez procéder comme suit:

  • Définissez le MediaInformation userActionStates avec les préférences de l'utilisateur lors du chargement d'un élément multimédia.
  • Interceptez les messages USER_ACTION et déterminez l'action demandée.
  • Mettez à jour le UserActionState MediaInformation pour mettre à jour l'UI.

L'extrait de code suivant intercepte la requête LOAD et insère le MediaInformation de LoadRequestData. Dans ce cas, l'utilisateur aime le contenu en cours de chargement.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

L'extrait de code suivant intercepte le message USER_ACTION et gère l'appel du backend avec la modification demandée. Il effectue ensuite un appel pour mettre à jour le UserActionState sur le récepteur.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

L'extrait de code suivant simule un appel à un service de backend. La fonction vérifie le UserActionRequestData pour voir le type de modification demandé par l'utilisateur et n'effectue un appel réseau que si l'action est acceptée par le backend.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

L'extrait de code suivant utilise UserActionRequestData et ajoute ou supprime UserActionState de MediaInformation. La mise à jour de l'UserActionState de MediaInformation modifie l'état du bouton associé à l'action demandée. Cette modification est reflétée dans l'UI des commandes d'écran connecté, l'application de télécommande et l'UI Android TV. Il est également diffusé via les messages MediaStatus sortants pour mettre à jour l'interface utilisateur de la manette développée pour les expéditeurs iOS et Android.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

Commandes vocales

Les commandes multimédias suivantes sont actuellement compatibles avec le SDK Web Receiver pour les appareils avec Assistant Google intégré. Les implémentations par défaut de ces commandes se trouvent dans cast.framework.PlayerManager.

Commande Description
Lire Lire ou reprendre la lecture à partir d'une mise en pause
Pause Mets en pause le contenu en cours de lecture.
Précédent Passer à l'élément multimédia précédent dans la file d'attente
Suivant Passer à l'élément multimédia suivant dans la file d'attente
Arrêter Arrête le contenu multimédia en cours de lecture.
Aucune répétition Désactive la répétition des éléments multimédias de la file d'attente une fois la lecture du dernier élément en attente.
Répéter le single Répète indéfiniment le contenu multimédia en cours de lecture.
Tout répéter Répète tous les éléments de la file d'attente une fois que le dernier élément de la file d'attente a été lu.
Tout répéter et lire en mode aléatoire Lorsque la lecture du dernier élément de la file d'attente est terminée, passez en mode aléatoire et répétez tous les éléments de la file d'attente.
Aléatoire lire les éléments multimédias de votre file d'attente en mode aléatoire.
Activer / Désactiver les sous-titres Activer / Désactiver les sous-titres pour vos contenus multimédias L'option "Activer / Désactiver" est également disponible pour chaque langue.
Rechercher une heure absolue Accède à l'heure absolue spécifiée.
Rechercher un par rapport à l'heure par rapport à l'heure actuelle Avance ou revient en arrière selon la période spécifiée par rapport à la durée de lecture actuelle.
Rejouer Redémarrez le contenu multimédia en cours de lecture ou lancez le dernier élément multimédia lu si rien n'est en cours de lecture.
Définir la vitesse de lecture Varier la vitesse de lecture des contenus multimédias. Cela devrait être géré par défaut. Vous pouvez utiliser l'intercepteur de messages SET_PLAYBACK_RATE pour ignorer les requêtes de débit entrantes.

Commandes vocales compatibles avec les contenus multimédias

Pour empêcher une commande vocale de déclencher une commande multimédia sur un appareil avec Assistant Google intégré, vous devez d'abord définir les commandes multimédias compatibles que vous prévoyez de prendre en charge. Vous devez ensuite appliquer ces commandes en activant la propriété CastReceiverOptions.enforceSupportedCommands. L'UI des expéditeurs du SDK Cast et des appareils tactiles sera modifiée pour refléter ces configurations. Si l'indicateur n'est pas activé, les commandes vocales entrantes s'exécutent.

Par exemple, si vous autorisez PAUSE à partir de vos applications émettrices et de vos appareils tactiles, vous devez également configurer votre récepteur pour qu'il reflète ces paramètres. Une fois configurées, les commandes vocales entrantes seront ignorées si elles ne figurent pas dans la liste des commandes compatibles.

Dans l'exemple ci-dessous, nous fournissons le CastReceiverOptions au démarrage de CastReceiverContext. Nous avons ajouté la prise en charge de la commande PAUSE et forcé le lecteur à n'accepter que cette commande. Désormais, si une commande vocale demande une autre opération telle que SEEK, elle est refusée. L'utilisateur est informé que la commande n'est pas encore prise en charge.

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

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

Vous pouvez appliquer une logique distincte à chaque commande que vous souhaitez restreindre. Supprimez l'option enforceSupportedCommands. Vous pouvez ainsi intercepter le message entrant pour chaque commande que vous souhaitez restreindre. Ici, nous interceptons la requête fournie par le SDK afin que les commandes SEEK envoyées aux appareils avec Assistant Google intégré ne déclenchent pas de recherche dans votre application Web Receiver.

Pour les commandes multimédias non compatibles avec votre application, renvoyez un motif d'erreur approprié, tel que NOT_SUPPORTED.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

Arrière-plan de l'activité vocale

Si la plate-forme Cast met le son de votre application en arrière-plan en raison d'une activité de l'Assistant, telle que l'écoute de la voix de l'utilisateur ou la réponse, un message FocusState de NOT_IN_FOCUS est envoyé à l'application Web Receiver lorsque l'activité démarre. Un autre message avec IN_FOCUS est envoyé à la fin de l'activité. En fonction de votre application et du contenu multimédia en cours de lecture, vous pouvez le suspendre lorsque FocusState est défini sur NOT_IN_FOCUS en interceptant le type de message FOCUS_STATE.

Par exemple, il peut être judicieux de mettre en pause la lecture d'un livre audio si l'Assistant répond à une requête utilisateur.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

Langue des sous-titres spécifiée par la voix

Lorsqu'un utilisateur n'indique pas explicitement la langue des sous-titres, la langue utilisée pour les sous-titres est celle dans laquelle la commande a été prononcée. Dans ces scénarios, le paramètre isSuggestedLanguage du message entrant indique si la langue associée a été suggérée ou demandée explicitement par l'utilisateur.

Par exemple, isSuggestedLanguage est défini sur true pour la commande "Ok Google, activer les sous-titres", car la langue a été déduite de celle dans laquelle la commande a été énoncée. Si la langue est demandée explicitement, par exemple dans "Ok Google, active les sous-titres en anglais", isSuggestedLanguage est défini sur false.

Métadonnées et diffusion vocale

Bien que les commandes vocales soient gérées par défaut par Web Receiver, vous devez vous assurer que les métadonnées de votre contenu sont complètes et exactes. Cela garantit que les commandes vocales sont correctement gérées par l'Assistant et que les métadonnées s'affichent correctement sur les nouveaux types d'interfaces, tels que l'application Google Home et les écrans connectés tels que Google Home Hub.

Transfert de diffusion

La préservation de l'état de la session constitue la base du transfert de flux, qui permet aux utilisateurs de déplacer des flux audio et vidéo existants d'un appareil à l'autre à l'aide de commandes vocales, de l'application Google Home ou d'écrans connectés. La lecture du contenu multimédia s'arrête sur un appareil (la source) et continue sur un autre (la destination). Tout appareil Cast doté de la dernière version du micrologiciel peut servir de sources ou de destinations lors d'un transfert de flux.

Voici le flux des événements pour le transfert de diffusion:

  1. Sur l'appareil source :
    1. La lecture du contenu multimédia s'arrête.
    2. L'application Web Receiver reçoit une commande pour enregistrer l'état actuel du contenu multimédia.
    3. L'application Web Receiver est arrêtée.
  2. Sur l'appareil de destination :
    1. L'application Web Receiver est chargée.
    2. L'application Web Receiver reçoit une commande pour restaurer l'état du contenu multimédia enregistré.
    3. Reprise de la lecture du contenu multimédia.

Voici quelques éléments liés à l'état d'un contenu multimédia:

  • Position ou code temporel spécifique du titre, de la vidéo ou de l'élément multimédia.
  • Il est placé dans une file d'attente plus large (par exemple, une playlist ou une radio d'artiste).
  • L'utilisateur authentifié
  • État de la lecture (lecture ou mise en pause, par exemple)

Activer le transfert de diffusion

Pour implémenter le transfert de flux pour votre récepteur Web:

  1. Mettez à jour supportedMediaCommands avec la commande STREAM_TRANSFER :
    playerManager.addSupportedMediaCommands(
    cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. Vous pouvez éventuellement ignorer les intercepteurs de messages SESSION_STATE et RESUME_SESSION, comme décrit dans la section Conserver l'état de la session. Ne les remplacez que si des données personnalisées doivent être stockées dans l'instantané de session. Sinon, l'implémentation par défaut pour conserver les états de session permettra le transfert de flux.

Préserver l'état de la session

Le SDK Web Receiver fournit une implémentation par défaut pour les applications Web Receiver afin de conserver les états de session en prenant un instantané de l'état actuel du média, en convertissant l'état en requête de chargement, puis en reprenant la session avec la requête de chargement.

La requête de chargement générée par le récepteur Web peut être remplacée dans l'intercepteur de messages SESSION_STATE si nécessaire. Si vous souhaitez ajouter des données personnalisées à la requête de chargement, nous vous suggérons de les placer dans loadRequestData.customData.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

Les données personnalisées peuvent être extraites de loadRequestData.customData, dans l'intercepteur de messages RESUME_SESSION.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

Préchargement du contenu

Web Receiver prend en charge le préchargement des éléments multimédias après l'élément de lecture en cours dans la file d'attente.

L'opération de préchargement précharge plusieurs segments des éléments à venir. La spécification est effectuée sur la valeur preloadTime de l'objet QueueItem (la valeur par défaut est de 20 secondes si elle n'est pas fournie). La durée est exprimée en secondes par rapport à la fin de l'élément en cours de lecture . Seules les valeurs positives sont valides. Par exemple, si la valeur est de 10 secondes, cet élément sera préchargé 10 secondes avant la fin de l'élément précédent. Si le temps de préchargement est supérieur à celui restant pour l'élément currentItem, le préchargement aura lieu dès que possible. Ainsi, si une valeur de préchargement très élevée est spécifiée sur queueItem, l'élément suivant peut déjà être préchargé chaque fois que nous lisons l'élément actuel. Toutefois, nous laissons le paramètre et le choix au développeur, car cette valeur peut affecter la bande passante et les performances de streaming de l'élément en cours de lecture.

Par défaut, le préchargement est compatible avec les contenus en streaming HLS, DASH et fluides.

Les fichiers vidéo et audio MP4 standards, tels que MP3, ne sont pas préchargés, car les appareils Cast n'acceptent qu'un seul élément multimédia et ne peuvent pas être utilisés pour précharger lorsqu'un élément de contenu existant est toujours en cours de lecture.

Messages personnalisés

L'échange de messages est la méthode d'interaction principale pour les applications Web receiver.

Un expéditeur envoie des messages à un récepteur Web à l'aide des API de l'expéditeur pour la plate-forme exécutée par l'expéditeur (Android, iOS, Web). L'objet d'événement (qui est la manifeste d'un message) transmis aux écouteurs d'événements comporte un élément de données (event.data) dont les données s'appuient sur les propriétés du type d'événement spécifique.

Une application réceptrice Web peut choisir d'écouter les messages sur un espace de noms spécifié. Ainsi, on considère que l'application Web Receiver prend en charge ce protocole d'espace de noms. Il revient ensuite à tous les expéditeurs connectés qui souhaitent communiquer sur cet espace de noms d'utiliser le protocole approprié.

Tous les espaces de noms sont définis par une chaîne et doivent commencer par "urn:x-cast:" suivi d'une chaîne. Exemple : "urn:x-cast:com.example.cast.mynamespace".

Voici un extrait de code permettant à Web Receiver d'écouter les messages personnalisés provenant d'expéditeurs connectés:

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

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

De même, les applications Web Receiver peuvent tenir les expéditeurs informés de l'état du récepteur Web en envoyant des messages aux expéditeurs connectés. Une application réceptrice Web peut envoyer des messages à l'aide de sendCustomMessage(namespace, senderId, message) sur CastReceiverContext. Un récepteur Web peut envoyer des messages à un expéditeur individuel, en réponse à un message reçu ou en raison d'un changement d'état de l'application. Au-delà des messages point à point (avec une limite de 64 Ko), un récepteur Web peut également diffuser des messages à tous les expéditeurs connectés.

Caster des appareils audio

Pour en savoir plus sur la lecture audio uniquement, consultez le guide Google Cast pour les appareils audio.

Android TV

Cette section explique comment Google Web Receiver utilise vos entrées pour la lecture et sa compatibilité avec Android TV.

Intégrer votre application à la télécommande

Google Web Receiver s'exécutant sur l'appareil Android TV traduit l'entrée des entrées de commande de l'appareil (télécommande portable) en tant que messages de lecture multimédia définis pour l'espace de noms urn:x-cast:com.google.cast.media, comme décrit dans la section Messages de lecture multimédia. Votre application doit prendre en charge ces messages pour contrôler la lecture de contenus multimédias de l'application afin d'autoriser la commande de lecture de base à partir des entrées de commande d'Android TV.

Consignes de compatibilité avec Android TV

Voici quelques recommandations et les pièges courants à éviter pour vous assurer que votre application est compatible avec Android TV:

  • Sachez que la chaîne du user-agent contient à la fois "Android" et "CREASON" ; certains sites peuvent rediriger vers un site mobile uniquement parce qu'ils détectent le libellé "Android". Ne partez pas du principe que "Android" dans la chaîne du user-agent indique toujours un utilisateur mobile.
  • La pile multimédia d'Android peut utiliser un GZIP transparent pour récupérer les données. Assurez-vous que vos données multimédias peuvent répondre à Accept-Encoding: gzip.
  • Les événements multimédias HTML5 d'Android TV peuvent être déclenchés à des moments différents de ceux de Chromecast. Cela peut révéler des problèmes qui ont été masqués sur Chromecast.
  • Lorsque vous mettez à jour le contenu multimédia, utilisez les événements associés déclenchés par les éléments <audio>/<video>, tels que timeupdate, pause et waiting. Évitez d'utiliser des événements liés à la mise en réseau tels que progress, suspend et stalled, car ils ont tendance à dépendre de la plate-forme. Pour en savoir plus sur la gestion des événements multimédias dans votre récepteur, consultez la section Événements multimédias.
  • Lorsque vous configurez les certificats HTTPS de votre site destinataire, veillez à inclure des certificats CA intermédiaires. Pour le vérifier, consultez la page du test SSL de Qualsys. Si le chemin de certification de confiance pour votre site comprend un certificat CA portant le libellé "Téléchargement supplémentaire", il est possible que celui-ci ne se charge pas sur les plates-formes Android.
  • Alors que Chromecast affiche la page du récepteur sur un plan graphique 720p, d'autres plates-formes Cast, telles qu'Android TV, peuvent afficher la page jusqu'à 1080p. Assurez-vous que la page de destination s'adapte de manière fluide à différentes résolutions.