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

1. Descripción general

Logotipo de Google Cast

En este codelab, se describe cómo compilar una app de Custom Web Receiver 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. El SDK de Cast te permite agregar los componentes de la IU necesarios según la lista de tareas de diseño de Google Cast.

Te proporcionamos la lista de tareas de diseño de Google Cast para estandarizar las implementaciones de Cast y 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 los clips de descanso
  • Cómo personalizar el comportamiento predeterminado de las pausas durante la búsqueda

Requisitos

Experiencia

Antes de continuar con este codelab, asegúrate de tener la siguiente experiencia.

  • Conocimientos generales sobre desarrollo web
  • Compila aplicaciones de Cast Web Receiver.

¿Cómo usarás este instructivo?

Ler Leer y completar los ejercicios

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

Principiante Intermedio Avanzado

2. Obtén el código de muestra

Presiona el siguiente botón para descargar el código de muestra completo 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, debe estar alojado en algún lugar donde el dispositivo pueda alcanzarlo. Si ya tienes un servidor disponible que admite 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 elegiste, navega a app-start y, luego, inicia tu servidor.

Toma nota de 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 una app receptora personalizada, como las que se compilan en este codelab, en dispositivos Chromecast. Una vez que hayas registrado tu aplicación, se generará un ID de aplicación que se debe configurar en la aplicación emisora para iniciar la aplicación de Web Receiver.

Imagen de Google Cast SDK Developer Console con el botón "Add New Application" destacado

Haz clic en "Add new application".

Imagen de la pantalla "New Receiver Application" con la opción "Custom Receiver" destacada

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

Imagen de la pantalla "New Custom Receiver" que muestra una URL que alguien está escribiendo en el campo "Receiver Application URL"

Ingresa los detalles del nuevo receptor. Asegúrate de usar la URL que apunta a donde planeas alojar tu aplicación de Web Receiver. Toma nota del ID de aplicación que genera la consola una vez que registras la aplicación. La aplicación del remitente 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. Para realizar este codelab, se recomienda trabajar con una aplicación receptora no publicada.

Imagen de la consola del SDK de Google Cast para desarrolladores con el botón "Add New Device" destacado

Haz clic en "Add new Device".

Imagen del diálogo "Agregar dispositivo receptor de transmisión"

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 Play Console del SDK de Google Cast

La app receptora y el dispositivo tardarán entre 5 y 15 minutos en estar listos para la prueba. Luego de esperar entre 5 y 15 minutos, debes reiniciar el dispositivo Cast.

5. Prepara el proyecto inicial

Antes de comenzar este codelab, puede ser útil revisar 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:

  1. Selecciona el directorio ícono de carpetaapp-start de la descarga del código de muestra.
  2. Abre js/receiver.js y index.html

Ten en cuenta que, a medida que trabajas en este codelab, la solución de hosting web que elegiste debe actualizarse 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ó, el codelab utiliza una aplicación emisora 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 la app del receptor que se te proporcionó en la Consola para desarrolladores del SDK de Cast y haz clic en Establecer para configurar la app del remitente para las pruebas.

Nota: Si ves que no aparece el ícono de transmisión, asegúrate de que el Web Receiver y los dispositivos de transmisión estén registrados correctamente en la Consola para desarrolladores de Cast. Si aún no lo hiciste, reinicia los dispositivos de transmisión que acabas 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. Estos se describen con más detalle a continuación.

index.html

Este archivo html contiene la IU de nuestra app receptora proporcionada por el elemento cast-media-player. También carga las bibliotecas del SDK de CAF y de Cast Debug Logger.

receiver.js

Esta secuencia de comandos administra toda la lógica de nuestra app receptora. En este momento, contiene un receptor básico de CAF para inicializar el contexto de Cast y cargar un recurso de video durante la inicialización. También se agregaron algunas capacidades de registro de depuración para proporcionar registros a la herramienta Cast and Command.

6. Agrega VMAP a tu contenido

El SDK de Cast Web Receiver proporciona compatibilidad con los anuncios especificados a través de playlists con múltiples anuncios de video digitales, también conocidas como VMAP. La estructura XML especifica las pausas publicitarias de un contenido multimedia y sus metadatos de clips de pausas 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 del 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 correlacionador aleatorio para garantizar que las solicitudes posteriores a la misma URL generen una plantilla XML con pausas publicitarias que aún no se hayan visto.

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 y, luego, el contenido principal.

7. Agrega VAST a tu contenido

Como se mencionó anteriormente, el SDK de Web Receiver admite 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, coméntalo.

Copia lo siguiente en tu archivo js/receiver.js después del interceptor de solicitudes de carga. Contiene seis clips de interrupciones de VAST de DoubleClick y un valor de correlator aleatorio. Estos clips de descanso se asignan a 5 descansos. El position de cada pausa se establece en un tiempo en segundos relativo al contenido principal, incluidas las pausas previas al video (position establecido en 0) y las pausas posteriores al 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. 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 comandos, haz clic en el ícono de transmisión. Se deben reproducir los anuncios de VAST y, luego, el contenido principal.

8. Cómo omitir pausas publicitarias

CAF tiene una clase llamada BreakManager que te ayuda a implementar reglas comerciales personalizadas para los comportamientos de los anuncios. Una de estas funciones permite que las aplicaciones omitan de forma programática los descansos y los clips de descanso según 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 posteriores al video. Cuando se usan los anuncios de VAST configurados en la sección anterior, se definen 5 pausas: 1 pausa previa al video, 3 pausas durante el video (a los 15, 60 y 100 segundos) y, por último, una pausa posterior al video. Después de completar los pasos, solo se omitirán los anuncios previos al video y 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 interrupciones. 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 corte publicitario que ocurra antes de los 30 segundos, teniendo en cuenta los cortes 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 corte. Configúralo 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: Devolver null aquí omite el procesamiento de BreakClip. Si un Break no tiene clips de intermedio definidos, se omite el intermedio.

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 procesar los anuncios VAST. Ten en cuenta que no se reproducen los anuncios previos al video ni los primeros durante el video (cuyo position es de 15 segundos).

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

Cuando se buscan pausas anteriores, 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. 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. 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 mira el descanso, se reanuda la reproducción del contenido principal desde la posición seekTo. Si no existe tal interrupción, no se reproduce ninguna interrupción 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 uno o más cortes. La función de devolución de llamada recibe un objeto que contiene todos los cortes entre la posición seekFrom y la posición seekTo. Luego, la aplicación debe modificar y devolver el objeto BreakSeekData.

Para mostrar su uso, el siguiente ejemplo anula el comportamiento predeterminado tomando todos los cortes que se buscaron y reproduciendo 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 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;
});

Nota: Si la función no devuelve un valor o si devuelve null, no se reproducen interrupciones.

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 procesar los anuncios VAST. Ten en cuenta que no se reproducen los anuncios previos al video ni los primeros durante el video (cuyo position es de 15 segundos).

Espera a que el tiempo de reproducción llegue a los 30 segundos para superar todos los cortes que omite el interceptor de carga de clips de corte. Una vez que llegues a la posición deseada, envía un comando de búsqueda navegando a la pestaña Control de medios. Completa 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 interrupciones. Ahora, el comportamiento predeterminado debería anularse 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 Cast Receiver más reciente.

Para obtener más detalles, consulta la guía para desarrolladores de pausas publicitarias.