1. Descripción general
En este codelab, se describe cómo compilar una app de receptor web personalizado que usa la API de Cast Ad Breaks.
¿Qué es Google Cast?
Google Cast permite a los usuarios transmitir contenido desde un dispositivo móvil a una TV. De esa manera, los usuarios pueden usar su dispositivo móvil como control remoto de modo que se reproduzca contenido multimedia en la TV.
El SDK de Google Cast posibilita que extiendas tu app para controlar una TV o un sistema de sonido. Este SDK te permite agregar los componentes de IU necesarios según la lista de tareas de diseño de Google Cast.
La lista de tareas de diseño de Google Cast sirve para estandarizar las implementaciones de Cast y lograr que las experiencias de los usuarios sean intuitivas en todas las plataformas compatibles.
¿Qué compilaremos?
Cuando completes este codelab, habrás creado un receptor de Cast que aprovecha la API de Break.
Qué aprenderás
- Cómo incluir pausas de VMAP y VAST en el contenido para Cast
- Cómo omitir clips de pausa
- Cómo personalizar el comportamiento de pausa predeterminado en la búsqueda
Requisitos
- El navegador Google Chrome más reciente
- Servicio de hosting HTTPS, como Firebase Hosting o ngrok.
- Un dispositivo Google Cast, como Chromecast o Android TV, que esté configurado con acceso a Internet
- Una TV o un monitor con entrada HDMI o un dispositivo Google Home Hub
Experiencia
Asegúrate de tener la siguiente experiencia antes de continuar con este codelab.
- Conocimientos generales de desarrollo web
- Compila aplicaciones de receptor web de Cast.
¿Cómo usarás este instructivo?
¿Cómo calificarías tu experiencia con la compilación de apps web?
2. Obtén el código de muestra
Descarga todo el código de muestra en tu computadora:
y descomprimir el archivo ZIP que se descargó.
3. Implementa el receptor de forma local
Para poder usar tu receptor web con un dispositivo de transmisión, este debe estar alojado en un lugar donde el dispositivo pueda acceder a él. Si ya tienes un servidor disponible que admita https, omite las siguientes instrucciones y anota la URL, ya que la necesitarás en la siguiente sección.
Si no tienes un servidor disponible para usar, puedes usar Firebase Hosting o ngrok.
Ejecuta el servidor
Una vez que hayas configurado el servicio que elijas, navega a app-start y comienza a usar el servidor.
Anota la URL de tu receptor alojado. La usarás en la siguiente sección.
4. Registra una aplicación en Play Console de Cast
Debes registrar tu aplicación para poder ejecutar un receptor personalizado, como el que se compila en este codelab, en dispositivos Chromecast. Una vez que hayas registrado la aplicación, se generará un ID de aplicación que la aplicación del remitente debe configurar para iniciar la aplicación del receptor web.
Haz clic en "Add new application"
Selecciona "Custom Receiver", que es lo que estamos compilando.
Ingresa los detalles del nuevo receptor. Asegúrate de usar la URL que apunta al lugar donde planeas alojar tu aplicación de receptor web. Toma nota del ID de aplicación que genera la consola una vez que registres la aplicación. La aplicación emisora se configurará para usar ese identificador en una sección posterior.
También debes registrar un dispositivo Google Cast para que pueda acceder a la aplicación receptora antes de publicarla. Una vez que publiques la aplicación receptora, estará disponible para todos los dispositivos Google Cast. A los fines de este codelab, se recomienda trabajar con una aplicación receptora no publicada.
Haz clic en "Add new Device".
Ingresa el número de serie impreso en la parte posterior del dispositivo de transmisión y asígnale un nombre descriptivo. También puedes encontrar el número de serie si transmites la pantalla en Chrome cuando accedes a la Consola del SDK de Google Cast para programadores
El receptor y el dispositivo tardarán entre 5 y 15 minutos en estar listos para la prueba. Después de esperar entre 5 y 15 minutos, debes reiniciar el dispositivo de transmisión.
5. Prepara el proyecto de inicio
Antes de comenzar este codelab, puede resultarte útil consultar la guía para desarrolladores de anuncios, que proporciona una descripción general de las APIs de pausas publicitarias.
Se debe agregar compatibilidad con Google Cast a la app de inicio que descargaste. A continuación, se detalla la terminología de Google Cast que se usa en este codelab:
- una app emisora se ejecuta en un dispositivo móvil o una laptop.
- una app receptora se ejecuta en el dispositivo Google Cast.
Ya puedes compilar sobre el proyecto inicial con tu editor de texto favorito:
- Selecciona el directorio
app-startde la descarga del código de muestra. - Abre
js/receiver.jse index.html.
Ten en cuenta que, a medida que trabajas en este codelab, debes actualizar la solución de hosting web que elegiste con los cambios que hagas. Asegúrate de enviar los cambios al sitio host cuando continúes validándolos y probándolos.
Diseño de la app
Como se mencionó, el codelab usa una aplicación de emisor para iniciar una sesión de Cast y una aplicación receptora que se modificará para usar las APIs de pausas publicitarias.
En este codelab, la herramienta de Cast y comandos actuará como el remitente web para iniciar la app receptora. Para comenzar, abre la herramienta en un navegador Chrome. Ingresa el ID de app del receptor que se te proporcionó en Play Console del SDK de Cast y haz clic en Configurar para configurar la app del remitente para realizar pruebas.
Nota: Si el ícono de transmisión no aparece, asegúrate de que el receptor web y los dispositivos de transmisión estén registrados correctamente en la Consola para desarrolladores de Cast. Si aún no lo hiciste, reinicia todos los dispositivos de transmisión que se acaban de registrar.
La app receptora es el objetivo principal de este codelab y consta de una vista principal definida en index.html y un archivo JavaScript llamado js/receiver.js. que se describen con más detalle a continuación.
index.html
Este archivo html contiene la IU de nuestra app receptora que proporciona el elemento cast-media-player. También carga las bibliotecas del SDK de CAF y el registrador de depuración de Cast.
receiver.js
Esta secuencia de comandos administra toda la lógica de nuestra app receptora. En este momento, contiene un receptor CAF básico para inicializar el contexto de transmisión y cargar un recurso de video tras la inicialización. También se agregaron algunas capacidades del registrador de depuración para proporcionar registros a la herramienta de Cast y Command.
6. Agrega VMAP a tu contenido
El SDK del receptor web de Cast admite anuncios especificados a través de playlists de varios anuncios de video digitales, también conocidas como VMAP. La estructura XML especifica las pausas publicitarias de un contenido multimedia y los metadatos de los clips de pausa asociados. Para insertar estos anuncios, el SDK proporciona la propiedad vmapAdsRequest en el objeto MediaInformation.
En el archivo js/receiver.js, crea un objeto VastAdsRequest. Busca la función interceptor de solicitudes LOAD y reemplázala por el siguiente código. Contiene una URL de etiqueta de VMAP de muestra de DoubleClick y proporciona un valor de correlador aleatorio para garantizar que las solicitudes posteriores a la misma URL generen una plantilla XML con las pausas publicitarias que aún no se miraron.
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;
});
Guarda los cambios en js/receiver.js y sube el archivo a tu servidor web. Para iniciar una sesión de transmisión en la herramienta de transmisión y comando, haz clic en el ícono de transmisión. Deberían reproducirse los anuncios de VMAP, seguidos del contenido principal.
7. Agrega VAST a tu contenido
Como se mencionó anteriormente, el SDK del receptor web es compatible con muchos tipos de anuncios. En esta sección, se destacan las APIs disponibles para integrar anuncios de plantilla de publicación de anuncios de video digital, también conocidos como VAST. Si implementaste el código de VMAP de la sección anterior, hazlo una observación.
Copia lo siguiente en tu archivo js/receiver.js después del interceptor de solicitudes de carga. Contiene seis clips de pausa de VAST de DoubleClick y un valor de correlador aleatorio. Estos clips de pausa se asignan a 5 pausas. El position de cada pausa se establece en un tiempo en segundos relacionado con el contenido principal, incluidas las pausas para anuncios previos al video (position establecido en 0) y al final del video (position establecido en -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}
];
};
Nota: La propiedad breakClipIds de una pausa es un array, lo que significa que se pueden asignar varios clips de pausa a cada una.
En tu js/receiver.js file, busca el interceptor de mensajes LOAD y reemplázalo por el siguiente código. Ten en cuenta que el trabajo de VMAP está comentado para mostrar anuncios de tipo 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;
});
Guarda los cambios en js/receiver.js y sube el archivo a tu servidor web. Para iniciar una sesión de transmisión en la herramienta de transmisión y comando, haz clic en el ícono de transmisión. Los anuncios VAST deben reproducirse, seguidos del contenido principal.
8. Omitir pausa publicitaria
CAF tiene una clase llamada BreakManager que te ayuda a implementar reglas empresariales personalizadas para los comportamientos de los anuncios. Una de estas funciones permite que las aplicaciones omitan o rompan clips de forma programática en función de alguna condición. En este ejemplo, se muestra cómo omitir una pausa publicitaria cuya posición se encuentra dentro de los primeros 30 segundos del contenido, pero no las pausas del anuncio final del video. Cuando se usan los anuncios VAST configurados en la sección anterior, se definen 5 pausas: 1 pausa para anuncios previos al video, 3 pausas para anuncios durante el video (a los 15, 60 y 100 segundos) y, por último, una pausa al final del video. Después de completar los pasos, solo se omitirán los anuncios previos al video y los anuncios durante el video cuya posición sea de 15 segundos.
Para ello, la aplicación debe llamar a las APIs disponibles a través de BreakManager para establecer un interceptor para la carga de pausas. Copia la siguiente línea en tu archivo js/receiver.js, después de las líneas que contienen las variables context y playerManager para obtener una referencia a la instancia.
const breakManager = playerManager.getBreakManager();
La aplicación debe configurar un interceptor con una regla para ignorar las pausas publicitarias que se produzcan antes de los 30 segundos y tener en cuenta las pausas posteriores al video (ya que sus valores de position son -1). Este interceptor funciona como el interceptor LOAD en PlayerManager, excepto que este es específico para cargar clips de pausa. Establece esto después del interceptor de solicitudes de LOAD y antes de la declaración de la función addVASTBreaksToMedia.
Copia lo siguiente en el archivo 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;
}
});
Nota: Si muestras null aquí, se omitirá el procesamiento de BreakClip. Si un Break no tiene clips de pausa definidos, se omite la pausa.
Guarda los cambios en js/receiver.js y sube el archivo a tu servidor web. Para iniciar una sesión de transmisión en la herramienta de transmisión y comando, haz clic en el ícono de transmisión. Los anuncios VAST deben procesarse. Ten en cuenta que los anuncios previos al video y el primer anuncio durante el video (cuyo position es de 15 segundos) no se reproducen.
9. Personaliza el comportamiento de la búsqueda de pausa
Cuando se saltan las pausas, la implementación predeterminada obtiene todos los elementos Break cuya posición está entre los valores seekFrom y seekTo de la operación de salto. En esta lista de pausas, el SDK reproduce el Break cuyo position es el más cercano al valor seekTo y cuya propiedad isWatched se establece en false. Luego, la propiedad isWatched de esa pausa se establece en true y el reproductor comienza a reproducir sus clips de pausa. Una vez que se reproduzca la pausa, se reanudará la reproducción del contenido principal desde la posición seekTo. Si no existe tal pausa, no se reproducirá ninguna pausa y se reanudará la reproducción del contenido principal en la posición seekTo.
Para personalizar qué pausas se reproducen en un salto, el SDK de Cast proporciona la API de setBreakSeekInterceptor en BreakManager. Cuando una aplicación proporciona su lógica personalizada a través de esa API, el SDK la llama cada vez que se realiza una operación de búsqueda en una o más pausas. La función de devolución de llamada recibe un objeto que contiene todos los saltos entre las posiciones seekFrom y seekTo. Luego, la aplicación debe modificar y mostrar el BreakSeekData.
Para mostrar su uso, en el siguiente ejemplo se anula el comportamiento predeterminado tomando todas las pausas que se buscaron y solo se reproduce la primera que aparece en la línea de tiempo.
Copia lo siguiente en tu archivo js/receiver.js, debajo de la definición en 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;
});
Nota: Si la función no muestra un valor o muestra null, no se reproducirán pausas.
Guarda los cambios en js/receiver.js y sube el archivo a tu servidor web. Para iniciar una sesión de transmisión en la herramienta de transmisión y comando, haz clic en el ícono de transmisión. Se deben procesar los anuncios VAST. Ten en cuenta que no se reproducen los anuncios previos al video ni el primer anuncio durante el video (cuyo position es de 15 segundos).
Espera a que el tiempo de reproducción alcance los 30 segundos para pasar todas las pausas que omite el interceptor de carga de clips de pausa. Una vez que llegues, navega a la pestaña Control multimedia para enviar un comando de búsqueda. Completa la entrada Seek Into Media con 300 segundos y haz clic en el botón TO. Ten en cuenta los registros impresos en el interceptor de búsqueda de pausa. Ahora se debe anular el comportamiento predeterminado para reproducir la pausa más cerca de la hora de seekFrom.
10. Felicitaciones
Ahora sabes cómo agregar anuncios a tu aplicación receptora con el SDK de app receptora de transmisión más reciente.
Para obtener más detalles, consulta la Guía para desarrolladores de pausas publicitarias.