1. Présentation
Cet atelier de programmation explique comment créer une application Web Receiver personnalisée qui utilise l'API Cast Ad Breaks.
Qu'est-ce que Google Cast ?
Google Cast permet aux utilisateurs de caster des contenus depuis un appareil mobile sur un téléviseur. Les utilisateurs peuvent ainsi utiliser leur appareil mobile comme télécommande pour la lecture de contenus multimédias sur leur téléviseur.
Le SDK Google Cast vous permet d'étendre votre application afin de contrôler un téléviseur ou un système audio. Le SDK Cast vous permet d'ajouter les composants d'interface utilisateur nécessaires en fonction de la checklist de conception Google Cast.
La checklist de conception de Google Cast vise à standardiser les implémentations Cast afin de rendre l'expérience utilisateur intuitive sur toutes les plates-formes compatibles.
Qu'allons-nous créer ?
À la fin de cet atelier de programmation, vous aurez créé un récepteur de cast qui exploite l'API Break.
Points abordés
- Inclure les coupures VMAP et VAST dans le contenu pour Cast
- Ignorer des extraits de coupure publicitaire
- Personnaliser le comportement de rupture par défaut dans la recherche
Ce dont vous avez besoin
- La dernière version du navigateur Google Chrome
- Un service d'hébergement HTTPS tel que Firebase Hosting ou ngrok
- Un appareil Google Cast, comme un Chromecast ou un Android TV, configuré pour accéder à Internet
- Un téléviseur ou un moniteur doté d'une entrée HDMI, ou un Google Home Hub
Expérience
Assurez-vous de disposer de l'expérience suivante avant de poursuivre cet atelier de programmation.
- Connaissances générales en développement Web
- Création d'applications Cast Web Receiver.
Comment allez-vous utiliser ce tutoriel ?
Comment évalueriez-vous votre expérience de création d'applications Web ?
2. Obtenir l'exemple de code
Télécharger tout l'exemple de code sur votre ordinateur...
puis décompresser le fichier ZIP téléchargé.
3. Déployer le récepteur localement
Pour que vous puissiez utiliser votre récepteur Web avec un appareil Cast, celui-ci doit être hébergé dans un endroit où l'appareil Cast est accessible. Si vous disposez déjà d'un serveur compatible avec HTTPS, ignorez les instructions ci-dessous et notez l'URL, car vous en aurez besoin dans la section suivante.
Si vous ne disposez d'aucun serveur, vous pouvez utiliser Firebase Hosting ou ngrok.
Exécuter le serveur
Une fois le service de votre choix configuré, accédez à app-start et démarrez votre serveur.
Notez l'URL de votre récepteur hébergé. Vous l'utiliserez dans la section suivante.
4. Enregistrer une application dans la console de développement Cast
Vous devez enregistrer votre application pour pouvoir exécuter un récepteur personnalisé, comme intégré dans cet atelier de programmation, sur les appareils Chromecast. Une fois votre application enregistrée, un identifiant d'application est généré. L'application émettrice doit être configurée pour lancer l'application Web receiver.
Cliquez sur "Ajouter une application".
Sélectionnez "Récepteur personnalisé". C'est ce que nous sommes en train de créer.
Saisissez les informations concernant votre nouveau récepteur. Assurez-vous d'utiliser l'URL qui pointe vers l'endroit où vous prévoyez d'héberger votre application Web Receiver. Notez l'ID application généré par la console une fois l'application enregistrée. L'application émettrice sera configurée pour utiliser cet identifiant dans une section ultérieure.
Vous devez également enregistrer un appareil Google Cast pour qu'il puisse accéder à votre application réceptrice avant de le publier. Une fois publiée, votre application réceptrice sera disponible pour tous les appareils Google Cast. Pour les besoins de cet atelier de programmation, il est recommandé d'utiliser une application réceptrice non publiée.
Cliquez sur "Ajouter un appareil"
Saisissez le numéro de série indiqué au dos de votre appareil Cast et attribuez-lui un nom descriptif. Vous pouvez également trouver le numéro de série en castant votre écran dans Chrome lorsque vous accédez à la console pour développeur du SDK Google Cast.
La préparation du récepteur et de l'appareil prend 5 à 15 minutes. Après 5 à 15 minutes d'attente, vous devez redémarrer l'appareil Cast.
5. Préparer le projet de démarrage
Avant de commencer cet atelier de programmation, il peut être utile de consulter le guide du développeur d'annonces, qui présente les API de coupure publicitaire.
La compatibilité avec Google Cast doit être ajoutée à l'application de démarrage que vous avez téléchargée. Voici quelques termes liés à Google Cast utilisés dans cet atelier de programmation:
- Une appli de type émetteur s'exécute sur un appareil mobile ou un ordinateur portable.
- Une appli de type récepteur s'exécute sur l'appareil Google Cast.
Vous êtes maintenant prêt à développer le projet de démarrage à l'aide de votre éditeur de texte préféré:
- Sélectionnez le répertoire
app-startdans le téléchargement de l'exemple de code. - Ouvrez
js/receiver.jset index.html.
Notez que vous devez suivre les modifications apportées à la solution d'hébergement Web que vous avez choisie tout au long de cet atelier de programmation. Veillez à transmettre les modifications au site hôte lorsque vous continuez à les valider et à les tester.
Conception de l'application
Comme indiqué, l'atelier de programmation utilise une application émettrice pour lancer une session Cast et une application réceptrice qui sera modifiée pour utiliser les API de coupure publicitaire.
Dans cet atelier de programmation, l'outil de diffusion et de commande fera office d'expéditeur Web pour lancer l'application de réception. Pour commencer, ouvrez l'outil dans le navigateur Chrome. Saisissez l'ID de l'application du récepteur qui vous a été fourni dans la Developer Console du SDK Cast, puis cliquez sur Définir afin de configurer l'application émettrice à des fins de test.
Remarque: Si vous ne voyez pas l'icône Cast, vérifiez que le récepteur Web et les appareils Cast sont correctement enregistrés dans la Play Console. Si vous ne l'avez pas déjà fait, arrêtez et redémarrez les appareils Cast qui viennent d'être enregistrés.
L'application réceptrice est l'objet principal de cet atelier de programmation. Elle se compose d'une vue principale définie dans index.html et d'un fichier JavaScript appelé js/receiver.js. Celles-ci sont décrites plus en détail ci-dessous.
index.html
Ce fichier HTML contient l'interface utilisateur de notre application réceptrice fournie par l'élément cast-media-player. Il charge également le SDK CAF et les bibliothèques du journal de débogage Cast.
receiver.js
Ce script gère toute la logique de notre application réceptrice. À l'heure actuelle, il contient un récepteur CAF de base qui permet d'initialiser le contexte de diffusion et de charger un élément vidéo lors de l'initialisation. Certaines fonctionnalités de l'enregistreur de débogage ont également été ajoutées pour permettre la journalisation dans l'outil Cast et Command.
6. Ajouter la norme VMAP à votre contenu
Le SDK Récepteur Web Cast est compatible avec les annonces spécifiées via les playlists d'annonces vidéo multiples, également appelées VMAP. La structure XML spécifie les coupures publicitaires d'un contenu multimédia et les métadonnées d'extraits de coupure associées. Pour insérer ces annonces, le SDK fournit la propriété vmapAdsRequest dans l'objet MediaInformation.
Dans le fichier js/receiver.js, créez un objet VastAdsRequest. Recherchez la fonction LOAD request interceptor (intercepteur de requêtes de chargement) et remplacez-la par le code suivant ci-dessous. Elle contient un exemple d'URL de tag VMAP provenant de DoubleClick, ainsi qu'une valeur de correlator aléatoire permettant de s'assurer que les demandes suivantes adressées à la même URL génèrent un modèle XML avec des coupures publicitaires qui n'ont pas encore été visionnées.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
const vmapUrl =
'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
Math.floor(Math.random() * Math.pow(10, 10));
let vmapRequest = new cast.framework.messages.VastAdsRequest();
vmapRequest.adTagUrl = vmapUrl;
loadRequestData.media.vmapAdsRequest = vmapRequest;
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
Enregistrez les modifications apportées à js/receiver.js et importez le fichier sur votre serveur Web. Lancez une session Cast dans l'outil Caster et de commandes en cliquant sur l'icône Cast. Les annonces VMAP doivent être diffusées, suivies du contenu principal.
7. Ajouter VAST à votre contenu
Comme indiqué précédemment, le SDK Web Receiver prend en charge de nombreux types d'annonces. Cette section présente les API disponibles pour intégrer des annonces VAST, également appelées modèle de diffusion d'annonces vidéo numériques. Si vous avez implémenté le code VMAP de la section précédente, mettez-le en commentaire.
Copiez le code suivant dans votre fichier js/receiver.js après l'intercepteur de requêtes de chargement. Elle contient six clips de rupture VAST provenant de DoubleClick, ainsi qu'une valeur de correlator aléatoire. Ces extraits sont attribués à cinq coupures. La position de chaque coupure publicitaire est définie sur une durée en secondes par rapport au contenu principal, y compris les coupures pré-roll (position définies sur 0) et post-roll (position définies sur -1).
const addVASTBreaksToMedia = (mediaInformation) => {
mediaInformation.breakClips = [
{
id: 'bc1',
title: 'bc1 (Pre-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('preroll')
}
},
{
id: 'bc2',
title: 'bc2 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc3',
title: 'bc3 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc4',
title: 'bc4 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc5',
title: 'bc5 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc6',
title: 'bc6 (Post-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('postroll')
}
}
];
mediaInformation.breaks = [
{id: 'b1', breakClipIds: ['bc1'], position: 0},
{id: 'b2', breakClipIds: ['bc2'], position: 15},
{id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
{id: 'b4', breakClipIds: ['bc5'], position: 100},
{id: 'b5', breakClipIds: ['bc6'], position: -1}
];
};
Remarque:La propriété breakClipIds d'une coupure publicitaire est un tableau, ce qui signifie que plusieurs coupures peuvent être attribuées à chaque coupure.
Dans js/receiver.js file, localisez l'intercepteur de messages LOAD et remplacez-le par le code suivant. Notez que le processus VMAP est mis en commentaire pour présenter des annonces de type VAST.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
// const vmapUrl =
// 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
// Math.floor(Math.random() * Math.pow(10, 10));
// let vmapRequest = new cast.framework.messages.VastAdsRequest();
// vmapRequest.adTagUrl = vmapUrl;
// loadRequestData.media.vmapAdsRequest = vmapRequest;
// Append VAST ad breaks to the MediaInformation.
addVASTBreaksToMedia(loadRequestData.media);
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
Enregistrez les modifications apportées à js/receiver.js et importez le fichier sur votre serveur Web. Lancez une session Cast dans l'outil Caster et de commandes en cliquant sur l'icône Cast. Les annonces VAST doivent être diffusées, suivies du contenu principal.
8. Coupure publicitaire ignorée
CAF propose une classe appelée BreakManager qui vous aide à implémenter des règles commerciales personnalisées pour les comportements d'annonces. L'une de ces fonctionnalités permet aux applications d'ignorer par programmation des coupures et des coupures de clips en fonction de certaines conditions. Cet exemple montre comment ignorer une coupure publicitaire dont la position est située dans les 30 premières secondes du contenu, sans les coupures post-roll. Lorsque vous utilisez les annonces VAST configurées dans la section précédente, cinq coupures sont définies: une coupure pré-roll, trois coupures mid-roll (à 15, 60 et 100 secondes), et enfin une coupure post-roll. Une fois ces étapes terminées, seules les annonces pré-roll et mid-roll dont la position est fixée à 15 secondes sont ignorées.
Pour ce faire, l'application doit appeler les API disponibles via BreakManager afin de définir un intercepteur pour l'interruption du chargement. Copiez la ligne suivante dans votre fichier js/receiver.js, après les lignes contenant les variables context et playerManager pour obtenir une référence à l'instance.
const breakManager = playerManager.getBreakManager();
L'application doit configurer un intercepteur avec une règle permettant d'ignorer les coupures publicitaires qui se produisent avant 30 secondes, tout en gardant à l'esprit les coupures post-roll (car leurs valeurs position sont -1). Cet intercepteur fonctionne comme l'intercepteur LOAD sur PlayerManager, à la différence que celui-ci est spécifique au chargement d'extraits de coupure publicitaire. Définissez ce paramètre après l'intercepteur de requêtes LOAD et avant la déclaration de la fonction addVASTBreaksToMedia.
Copiez le code suivant dans le fichier js/receiver.js.
breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
/**
* The code will skip playback of break clips if the break position is within
* the first 30 seconds.
*/
let breakObj = breakContext.break;
if (breakObj.position >= 0 && breakObj.position < 30) {
castDebugLogger.debug(
'MyAPP.LOG',
'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
return null;
} else {
return breakClip;
}
});
Remarque:Si vous renvoyez null ici, l'BreakClip en cours de traitement est ignorée. Si aucun extrait de coupure publicitaire n'est défini pour un Break, le saut en lui-même est ignoré.
Enregistrez les modifications apportées à js/receiver.js et importez le fichier sur votre serveur Web. Lancez une session Cast dans l'outil Caster et de commandes en cliquant sur l'icône Cast. Les annonces VAST doivent être traitées. Notez que les annonces pré-roll et mid-roll (dont la durée position dure 15 secondes) ne sont pas diffusées.
9. Personnaliser le comportement de recherche de coupure
Lorsque vous recherchez des coupures passées, l'implémentation par défaut obtient tous les éléments Break dont la position se trouve entre les valeurs seekFrom et seekTo de l'opération de recherche. À partir de cette liste de coupures, le SDK lit le Break dont la position est la plus proche de la valeur seekTo et dont la propriété isWatched est définie sur false. La propriété isWatched de cette coupure est ensuite définie sur true, et le lecteur commence à lire ses extraits. Une fois la pause visionnée, le contenu principal reprend la lecture à partir de la position seekTo. S'il n'existe aucune coupure de ce type, aucune coupure n'est lue, et la lecture du contenu principal reprend à la position seekTo.
Pour personnaliser l'interruption de la lecture lors d'une recherche, le SDK Cast fournit l'API setBreakSeekInterceptor dans BreakManager. Lorsqu'une application fournit sa logique personnalisée via cette API, le SDK l'appelle chaque fois qu'une opération de recherche est effectuée sur une ou plusieurs pauses. La fonction de rappel reçoit un objet contenant tous les sauts entre les positions seekFrom et seekTo. L'application doit ensuite modifier et renvoyer BreakSeekData.
Pour illustrer son utilisation, l'exemple ci-dessous remplace le comportement par défaut en prenant toutes les coupures recherchées et en ne lisant que la première qui apparaît dans la timeline.
Copiez le code suivant dans votre fichier js/receiver.js sous la définition de setBreakClipLoadInterceptor.
breakManager.setBreakSeekInterceptor((breakSeekData) => {
/**
* The code will play an unwatched break between the seekFrom and seekTo
* position. Note: If the position of a break is less than 30 then it will be
* skipped due to the setBreakClipLoadInterceptor code.
*/
castDebugLogger.debug(
'MyAPP.LOG',
'Break Seek Interceptor processing break ids ' +
JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));
// Remove all other breaks except for the first one.
breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
return breakSeekData;
});
Remarque:Si la fonction ne renvoie pas de valeur ou si elle renvoie null, aucune coupure n'est lue.
Enregistrez les modifications apportées à js/receiver.js et importez le fichier sur votre serveur Web. Lancez une session Cast dans l'outil Caster et de commandes en cliquant sur l'icône Cast. Les annonces VAST doivent être traitées. Notez que les annonces pré-roll et mid-roll (dont la durée position dure 15 secondes) ne sont pas diffusées.
Attendez que la durée de lecture atteigne 30 secondes pour dépasser toutes les coupures ignorées par l'intercepteur de chargement de clips. Lorsque vous avez atteint l'une de ces options, envoyez une commande de recherche en accédant à l'onglet Media Control (Commandes multimédias). Renseignez la valeur 300 secondes dans l'entrée Seek Into Media (Rechercher dans le média), puis cliquez sur le bouton TO (À). Notez les journaux imprimés dans l'intercepteur de recherche de coupure. Le comportement par défaut doit désormais être ignoré afin de rapprocher la coupure publicitaire de la valeur seekFrom.
10. Félicitations !
Vous savez maintenant ajouter des annonces à votre application réceptrice à l'aide de la dernière version du SDK Récepteur Cast.
Pour en savoir plus, consultez le guide du développeur sur les coupures publicitaires.