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 du contenu multimédia depuis un appareil mobile sur un téléviseur, et d'utiliser leur appareil mobile comme télécommande lors de la diffusion.
Le SDK Google Cast vous permet d'étendre les fonctionnalités de 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'UI (interface utilisateur) requis, en fonction de la checklist de conception Google Cast.
Cette checklist a été conçue pour 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 Cast qui tire parti de l'API Break.
Points abordés
- Inclure des pauses VMAP et VAST dans le contenu pour Cast
- Ignorer les clips d'interruption
- Personnaliser le comportement par défaut des pauses lors de la recherche
Prérequis
- 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 Chromecast ou Android TV, configuré pour accéder à Internet.
- Un téléviseur ou un moniteur dotés d'une entrée HDMI, ou un Google Home Hub
Expérience
Assurez-vous d'avoir l'expérience suivante avant de continuer cet atelier de programmation.
- Connaissances générales en développement Web.
- Créer des applications Web Receiver Cast.
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échargez l'intégralité de l'exemple de code sur votre ordinateur…
puis décompresser le fichier ZIP téléchargé.
3. Déployer le récepteur en local
Pour utiliser votre récepteur Web avec un appareil Cast, vous devez l'héberger à un emplacement auquel cet appareil a accès. Si vous disposez déjà d'un serveur compatible avec HTTPS, ignorez les instructions suivantes et notez l'URL, car vous en aurez besoin dans la section suivante.
Si vous ne disposez pas d'un 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 en aurez besoin dans la section suivante.
4. Enregistrer une application dans la console développeur Cast
Vous devez enregistrer votre application pour pouvoir exécuter un récepteur personnalisé, tel qu'il est intégré dans cet atelier de programmation, sur des appareils Chromecast. Une fois votre application enregistrée, un ID application est généré. L'application émettrice doit être configurée pour lancer l'application Web Receiver.
Cliquez sur "Add new application" (Ajouter une application).
Sélectionnez "Custom Receiver" (Récepteur personnalisé), c'est-à-dire ce que nous sommes en train de créer.
Saisissez les informations sur votre nouveau récepteur. Veillez à utiliser l'URL pointant vers l'emplacement où vous prévoyez d'héberger votre application Web Receiver. Notez l'ID d'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 sa publication. Une fois votre application réceptrice publiée, elle est accessible à tous les appareils Google Cast. Pour les besoins de cet atelier de programmation, il est conseillé d'utiliser une application réceptrice non publiée.
Cliquez sur "Add new Device" (Ajouter un nouvel appareil).
Saisissez le numéro de série indiqué au dos de votre appareil Cast et attribuez-lui un nom descriptif. Pour connaître le numéro de série, vous pouvez également caster votre écran dans Chrome lorsque vous accédez à la console développeur du SDK Google Cast.
Veuillez patienter entre 5 et 15 minutes pour que le récepteur et l'appareil soient prêts à être testés. Une fois cette période écoulée, vous devez redémarrer votre appareil Cast.
5. Préparer le projet de départ
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 d'insertion publicitaire.
Vous devez ajouter la compatibilité avec Google Cast à l'application de démarrage que vous avez téléchargée. Voici quelques termes 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 votre projet de départ à l'aide de votre éditeur de texte favori :
- Sélectionnez le répertoire
app-startà partir de l'exemple de code téléchargé. - Ouvrez
js/receiver.jset index.html.
Notez que, tout au long de cet atelier de programmation, la solution d'hébergement Web que vous avez choisie devrait être mise à jour avec les modifications apportées. Assurez-vous d'envoyer les modifications au site hôte lorsque vous continuez à les valider et à les tester.
Conception de l'application
Comme mentionné précédemment, 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 d'insertion publicitaire.
Dans cet atelier de programmation, l'outil Cast & Command servira d'expéditeur Web pour lancer l'application récepteur. Pour commencer, ouvrez l'outil dans un navigateur Chrome. Saisissez l'ID de l'application réceptrice qui vous a été fourni dans la console développeur du SDK Cast, puis cliquez sur Définir pour configurer l'application émettrice à des fins de test.
Remarque : Si l'icône Cast n'apparaît pas, assurez-vous que le Web Receiver et les appareils Cast sont correctement enregistrés dans la console Cast Developer. Si vous ne l'avez pas déjà fait, redémarrez tous les appareils Cast qui viennent d'être enregistrés.
L'application récepteur est l'objectif principal de cet atelier de programmation. Elle se compose d'une vue principale définie dans index.html et d'un fichier JavaScript nommé js/receiver.js. Ces éléments sont décrits plus en détail ci-dessous.
index.html
Ce fichier HTML contient l'UI de notre application réceptrice fournie par l'élément cast-media-player. Il charge également les bibliothèques CAF SDK et Cast Debug Logger.
receiver.js
Ce script gère toute la logique de notre application réceptrice. Actuellement, il contient un récepteur CAF de base pour initialiser le contexte Cast et charger un élément vidéo lors de l'initialisation. Certaines fonctionnalités de journalisation de débogage ont également été ajoutées pour fournir une journalisation à l'outil Cast & Command.
6. Ajouter VMAP à votre contenu
Le SDK Web Receiver Cast est compatible avec les annonces spécifiées dans les playlists VMAP (Digital Video Multiple Ad Playlists). La structure XML spécifie les coupures publicitaires d'un contenu multimédia et les métadonnées associées aux clips de coupure. 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. Localisez la fonction intercepteur de requête LOAD et remplacez-la par le code ci-dessous. Il contient un exemple d'URL de tag VMAP provenant de DoubleClick et fournit une valeur de corrélateur aléatoire pour s'assurer que les requêtes ultérieures envoyées à la même URL génèrent un modèle XML avec des pauses 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, puis importez le fichier sur votre serveur Web. Lancez une session Cast sur l'outil Cast and Command en cliquant sur l'icône Cast. Les annonces VMAP doivent être diffusées, suivies du contenu principal.
7. Ajouter VAST à votre contenu
Comme mentionné précédemment, le SDK Web Receiver est compatible avec de nombreux types d'annonces. Cette section présente les API disponibles pour intégrer les annonces Digital Video Ad Serving Template, également appelées VAST. Si vous avez implémenté le code VMAP de la section précédente, mettez-le en commentaire.
Copiez les éléments suivants dans votre fichier js/receiver.js après l'intercepteur de requête de chargement. Il contient six extraits d'annonces VAST de DoubleClick et une valeur de corrélateur aléatoire. Ces clips de pause sont attribués à cinq pauses. Le position de chaque pause est défini sur une durée en secondes par rapport au contenu principal, y compris les pauses pré-roll (position défini sur 0) et post-roll (position défini 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'un break est un tableau, ce qui signifie que plusieurs clips d'insertion peuvent être attribués à chaque break.
Dans votre js/receiver.js file, localisez l'intercepteur de message LOAD et remplacez-le par le code suivant. Notez que le code VMAP est mis en commentaire pour présenter les 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, puis importez le fichier sur votre serveur Web. Lancez une session Cast sur l'outil Cast and Command en cliquant sur l'icône Cast. Les annonces VAST doivent être diffusées, suivies du contenu principal.
8. Ignorer les coupures publicitaires
CAF dispose d'une classe appelée BreakManager qui vous aide à implémenter des règles commerciales personnalisées pour les comportements des annonces. L'une de ces fonctionnalités permet aux applications de passer des pauses et des extraits de pause de manière programmatique en fonction d'une condition. Cet exemple montre comment ignorer une coupure publicitaire dont la position se trouve dans les 30 premières secondes du contenu, mais pas les coupures post-roll. Lorsque vous utilisez les annonces VAST configurées dans la section précédente, cinq pauses sont définies : une pause pré-roll, trois pauses mid-roll (à 15, 60 et 100 secondes) et une pause post-roll. Une fois les étapes terminées, seules les annonces pré-roll et mid-roll dont la position est à 15 secondes sont ignorées.
Pour ce faire, l'application doit appeler les API disponibles via BreakManager afin de définir un intercepteur pour le chargement des pauses. 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 (dont les valeurs position sont -1). Cet intercepteur fonctionne comme l'intercepteur LOAD sur PlayerManager, sauf qu'il est spécifique au chargement des clips de coupure. Définissez-le après l'intercepteur de requête LOAD et avant la déclaration de fonction addVASTBreaksToMedia.
Copiez ce qui suit 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, le BreakClip en cours de traitement est ignoré. Si aucune séquence d'insertion n'est définie pour un Break, l'insertion elle-même est ignorée.
Enregistrez les modifications apportées à js/receiver.js, puis importez le fichier sur votre serveur Web. Lancez une session Cast sur l'outil Cast and Command en cliquant sur l'icône Cast. Les annonces VAST doivent être traitées. Notez que les annonces pre-roll et la première annonce mid-roll (dont la durée position est de 15 secondes) ne sont pas diffusées.
9. Personnaliser le comportement de recherche de pauses
Lors de la recherche d'interruptions passées, l'implémentation par défaut obtient tous les éléments Break dont la position se situe entre les valeurs seekFrom et seekTo de l'opération de recherche. À partir de cette liste d'interruptions, le SDK lit l'Break dont l'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 pause est ensuite définie sur true, et le lecteur commence à lire ses clips de pause. Une fois la pause publicitaire terminée, le contenu principal reprend la lecture à la position seekTo. Si aucune pause de ce type n'existe, aucune pause n'est lue et le contenu principal reprend la lecture à la position seekTo.
Pour personnaliser les pauses publicitaires qui sont lues 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 points d'arrêt entre la position seekFrom et la position seekTo. L'application doit ensuite modifier et renvoyer le BreakSeekData.
Pour montrer son utilisation, l'exemple ci-dessous remplace le comportement par défaut en prenant toutes les pauses qui ont été 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 pause n'est lue.
Enregistrez les modifications apportées à js/receiver.js, puis importez le fichier sur votre serveur Web. Lancez une session Cast sur l'outil Cast and Command en cliquant sur l'icône Cast. Les annonces VAST doivent être traitées. Notez que les annonces pre-roll et la première annonce mid-roll (dont la durée position est de 15 secondes) ne sont pas diffusées.
Attendez que la durée de lecture atteigne 30 secondes pour passer toutes les pauses ignorées par l'intercepteur de chargement des clips d'insertion publicitaire. Une fois le point atteint, envoyez une commande de recherche en accédant à l'onglet Contrôle du contenu multimédia. Remplissez le champ de saisie Seek Into Media (Rechercher dans le contenu multimédia) avec 300 secondes, puis cliquez sur le bouton TO (VERS). Notez les journaux imprimés dans l'intercepteur de recherche d'arrêt. Le comportement par défaut doit maintenant être remplacé pour que la pause soit lue plus près de l'heure seekFrom.
10. Félicitations
Vous savez maintenant comment 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 Ad Breaks.