1. Descripción general
En este codelab, se describe cómo compilar una app receptora web personalizada que use la API de pausas publicitarias de Cast.
¿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 hayas completado este codelab, habrás compilado un receptor de Cast que aproveche la API de Break.
Qué aprenderás
- Cómo incluir pausas de VMAP y VAST en el contenido para la transmisión
- Cómo omitir clips de pausa
- Cómo personalizar el comportamiento de interrupción predeterminado en la búsqueda
Requisitos
- La versión más reciente del navegador Google Chrome
- 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 sobre desarrollo web
- Cómo compilar aplicaciones de Cast Web Receiver
¿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 manera 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 próxima sección.
Si no tienes un servidor disponible, puedes usar Firebase Hosting o ngrok.
Ejecuta el servidor
Una vez que hayas configurado el servicio que elijas, navega a app-start y, luego, inicia tu servidor.
Toma nota de la URL de tu receptor alojado. Lo usarás en la próxima sección.
4. Registra una aplicación en Play Console de Cast
Debes registrar tu aplicación para poder ejecutar una app receptora personalizada, como se incluye en este codelab, en dispositivos Chromecast. Una vez que hayas registrado tu aplicación, se generará un ID de aplicación que indicará que la aplicación emisora debe estar configurada 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 de tu nuevo receptor. Asegúrate de usar la URL que apunta al lugar en el que planeas alojar tu aplicación de receptor web. Toma nota del ID de aplicación que genera la consola una vez que registras 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 de tu 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 Play Console del SDK de Google Cast.
El receptor y el dispositivo tardan 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.
Debes agregar compatibilidad con Google Cast a la app de inicio que descargaste. A continuación, se muestra parte de 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 tienes todo listo para compilar sobre el proyecto inicial usando 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ó anteriormente, en el codelab se usa una aplicación emisora para iniciar una sesión de transmisión y una aplicación receptora que se modificará para usar las APIs de pausa publicitaria.
En este codelab, la herramienta de Cast y comando actuará como el remitente web para iniciar la app receptora. Primero, ábrela en el navegador Chrome. Ingresa el ID de app receptora que se te proporcionó en Play Console para desarrolladores del SDK de Cast y haz clic en Configurar para configurar la app emisora para las 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 Play Console. Si aún no lo hiciste, reinicia todos los dispositivos de transmisión que se acaban de registrar.
La app receptora es el enfoque 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 el SDK de CAF y las bibliotecas de Cast Debug Logger.
receiver.js
Esta secuencia de comandos administra toda la lógica de nuestra app receptora. En este momento, incluye un receptor CAF básico para inicializar el contexto de transmisión y cargar un recurso de video después de la inicialización. También se agregaron algunas capacidades del registrador de depuración para proporcionar acceso a la herramienta de transmisión y comando.
6. Agregue VMAP a su contenido
El SDK de receptor web de transmisión proporciona compatibilidad con anuncios especificados a través de listas de reproducción de varios anuncios de video digitales, también conocida como VMAP. La estructura XML especifica las pausas publicitarias de un contenido multimedia y los metadatos de 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. Localiza la función interceptor de solicitudes de CARGAR y reemplázala por el siguiente código. Contiene una URL de etiqueta de VMAP de muestra de DoubleClick y proporciona un valor de correlator aleatorio para garantizar que las solicitudes posteriores a la misma URL generen una plantilla XML con pausas publicitarias que aún no se vieron.
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 digitales, también conocidos como VAST. Si implementaste el código VMAP de la sección anterior, márcalo como comentario.
Copia lo siguiente en tu archivo js/receiver.js después del interceptor de solicitud de carga. Contiene seis clips de pausa de VAST de DoubleClick y un valor de correlator 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 pausa.
En tu js/receiver.js file, busca el interceptor de mensajes LOAD y reemplázalo por el siguiente código. Tenga en cuenta que el trabajo de VMAP se comenta 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. Se deben reproducir los anuncios VAST seguidos del contenido principal.
8. Omitir pausa publicitaria
CAF tiene una clase llamada BreakManager que te ayuda a implementar reglas comerciales personalizadas para el comportamiento 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 durante el video que se encuentren en 15 segundos.
Para ello, la aplicación debe llamar a las APIs disponibles a través de BreakManager con el objetivo de configurar un interceptor para la carga en pausa. 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 cualquier pausa publicitaria que se produzca antes de los 30 segundos y tener en cuenta cualquier pausa al final del 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. Configúralo después del interceptor de solicitud CARGAR 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 omitirá 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 buscas saltos pasados, la implementación predeterminada obtiene todos los elementos Break cuya posición se encuentra entre los valores seekFrom y seekTo de la operación de búsqueda. 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. La propiedad isWatched de ese descanso se establece en true, y el jugador comienza a reproducir los 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 de reproducción 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, el siguiente ejemplo anula el comportamiento predeterminado. Para ello, se toman todos los descansos buscados y se reproduce solo el primero 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 si muestra null, no se reproducen 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. 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.
Espera a que el tiempo de reproducción alcance los 30 segundos para superar todas las pausas que omite el interceptor de carga de clips de pausa. Una vez que alcances el límite, navega a la pestaña Media Control para enviar un comando de búsqueda. Propaga la entrada Seek Into Media con 300 segundos y haz clic en el botón TO. Observa los registros impresos en el interceptor de búsqueda de interrupción. Ahora se debe anular el comportamiento predeterminado para reproducir la pausa más cerca del tiempo 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 sobre pausas publicitarias.