Cómo agregar compatibilidad con la API de pausas publicitarias para un receptor web

1. Descripción general

En este codelab, se explica cómo compilar una app receptora web personalizada que use la API de pausas publicitarias de transmisión.

¿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 se proporciona para estandarizar las implementaciones de Cast para 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 transmisión que aprovecha la API de Break.

Qué aprenderás

• Cómo incluir pausas de VMAP y VAST en el contenido para transmisión
• Cómo omitir clips de pausa
• Cómo personalizar el comportamiento predeterminado de pausa en la búsqueda

Requisitos

• El navegador más reciente de Google Chrome
• Servicio de hosting de 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 Google Home Hub

Experiencia

Asegúrate de tener la siguiente experiencia antes de continuar con este codelab.

• Conocimientos generales sobre el desarrollo web
• Cómo compilar aplicaciones de recepción de transmisión web

> ¿Tienes problemas de red? > Si te encuentras en una ubicación donde la red Wi-Fi no es confiable, puedes conectar el dispositivo Chromecast mediante un adaptador de Ethernet para

Chromecast o Chromecast con Google TV.

¿Cómo usarás este instructivo?

Ler Leer y completar los ejercicios

¿Cómo calificarías tu experiencia en la compilación de aplicaciones web?

Principiante Intermedio Avanzado

2. Obtén el código de muestra

Descarga todo el código de muestra en tu computadora...

Descargar código fuente

y descomprimir el archivo ZIP que se descargó.

> El repositorio del codelab cast-videos-cast contiene dos proyectos de muestra: > * app-start: el código de inicio sobre el que compilarás en este codelab * app-done: El código completo para la app de video de ejemplo finalizada.

3. Implementa la app receptora 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 alcanzarlo. 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, puedes usar Firebase Hosting o ngrok.

Ejecuta el servidor

Una vez que hayas configurado el servicio que deseas, navega hasta app-start y, luego, inicia tu servidor.

Toma nota de la URL de tu receptor alojado. Lo utilizarás en la próxima sección.

4. Registra una aplicación en la Consola para desarrolladores de Cast

> ¿No tienes una cuenta de desarrollador de Cast? Regístrate para obtener una cuenta en la Play Console del SDK de Google Cast y paga la tarifa de registro.

Debes registrar tu aplicación para poder ejecutar una app receptora personalizada, como se integra en este codelab, en dispositivos Chromecast. Una vez que hayas registrado tu aplicación, se generará un ID de aplicación que se deberá configurar en la aplicación de remitente para iniciar la aplicación Receptora web.

Haz clic en "Agregar nueva aplicación".

Selecciona "Custom Receiver", que es lo que estamos creando.

Ingresa los detalles del nuevo receptor. Asegúrate de utilizar la URL que dirija al lugar al 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 tu aplicación receptora, estará disponible para todos los dispositivos Google Cast. Para los fines de este codelab, se recomienda trabajar con una aplicación receptora no publicada.

Haz clic en "Agregar nuevo dispositivo".

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 la Consola para desarrolladores del SDK de Google Cast.

El receptor y el dispositivo demoran entre 5 y 15 minutos en estar listos para la prueba. Después de esperar entre 5 y 15 minutos, debes reiniciar tu dispositivo de transmisión.

5. Cómo preparar el proyecto Start

Antes de comenzar este codelab, te recomendamos revisar la guía para desarrolladores de anuncios, en la que se proporciona una descripción general de las APIs de pausas publicitarias.

Es necesario agregar compatibilidad con Google Cast a la app de inicio que descargaste. Los siguientes son algunos términos relacionados con Google Cast que se usan 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.

Ahora ya puedes compilar sobre el proyecto inicial con tu editor de texto favorito:

1. Selecciona el directorio app-start de la descarga del código de muestra.
2. Abre js/receiver.js e index.html

Ten en cuenta que, mientras trabajas en este codelab, debes actualizar la solución de hosting web que elegiste con los cambios realizados. 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, el codelab utiliza 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 transmisión y comando actuará como remitente web a fin de iniciar la app receptora. Para comenzar, abre la herramienta en un navegador Chrome. Ingresa el ID de la app receptora que se te proporcionó en la Consola para desarrolladores del SDK de Cast y haz clic en Configurar a fin de configurar la app emisora para las pruebas.

Nota: Si ves que 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 los dispositivos de transmisión que se hayan registrado.

La app receptora es el enfoque principal de este codelab y consta de una vista principal definida en index.html y un archivo de JavaScript llamado js/receiver.js. Estos 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. Por el momento, contiene 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 funciones del registrador de depuración para proporcionar registros de vuelta a las herramientas de transmisión y comando.

> ¿Quieres transmitir documentación? > Tenemos una documentación extensa para apps receptoras y emisoras de iOS, Android y Chrome.

6. Agrega VMAP a tu 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 digital, también conocidas como VMAP. La estructura XML especifica las pausas publicitarias de un contenido multimedia y sus metadatos de clip 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 solicitud de CARGA y reemplázala por el siguiente código. Contiene una URL de etiqueta de VMAP de ejemplo de DoubleClick y proporciona un valor 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 comandos, haz clic en el ícono de transmisión. Se deben reproducir los anuncios de VMAP, seguidos del contenido principal.

7. Agrega VAST a tu contenido

Como se mencionó anteriormente, el SDK de Web Receiver es compatible con muchos tipos de anuncios. En esta sección, se destacan las APIs disponibles para integrar anuncios con plantillas de publicación de anuncios de video digitales, también conocidos como VAST. Si implementaste el código de 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 marca como comentario 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 comandos, haz clic en el ícono de transmisión. Los anuncios de VAST deben reproducirse, seguidos del contenido principal.

8. Omisión de pausas publicitarias

El 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 de forma programática pausas y clips 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 en las pausas al final del video. Cuando se usan los anuncios de VAST configurados en la sección anterior, se definen 5 pausas: 1 pausa para el anuncio previo al video, 3 pausas para el anuncio 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 el anuncio previo al video y el anuncio 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 a fin de configurar 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 ocurran antes de los 30 segundos y tener en cuenta las pausas de anuncios finales 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. Establece esto después del interceptor de solicitud 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 se muestra null aquí, se omite el BreakClip que se procesa. Si un elemento Break no tiene ningún clip de pausa definido, se omitirá la pausa en sí.

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 comandos, haz clic en el ícono de transmisión. Los anuncios de VAST deben procesarse. Ten en cuenta que no se reproducen los anuncios previos al video ni anuncios durante el video (cuyos position son 15 segundos).

9. Personalizar el comportamiento de la búsqueda de pausas

Cuando se buscan pausas pasadas, 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. A partir de esta lista de pausas, el SDK reproduce el Break cuyo position está más cerca del valor seekTo y cuya propiedad isWatched está establecida en false. La propiedad isWatched de la pausa se establece en true y el reproductor comienza a reproducir los clips de pausa. Una vez que se reproduce la pausa, se reanuda la reproducción del contenido principal desde la posición seekTo. Si no existe tal pausa, no se reproduce ninguna pausa y se reanuda la reproducción del contenido principal en la posición seekTo.

Para personalizar qué pausas se reproducen en una búsqueda, 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, ya que toma todas las pausas que se buscaron y solo 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 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 comandos, haz clic en el ícono de transmisión. Los anuncios de VAST deben procesarse. Ten en cuenta que no se reproducen los anuncios previos al video ni anuncios durante el video (cuyos position son 15 segundos).

Espera a que el tiempo de reproducción llegue a los 30 segundos para superar todas las pausas que omite el interceptor de carga de clip de pausa. Una vez alcanzado, envía un comando de búsqueda desde la pestaña Control de medios. 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 ruptura. 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 la 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.

> ¿Quieres ver más contenido de Cast? > Consulta los otros codelabs de Cast y nuestras apps de ejemplo en GitHub.