Configura el SDK de IMA para la DAI

Los SDKs de IMA facilitan la integración de anuncios multimedia en tus sitios web y aplicaciones. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administrar la reproducción de anuncios en tus aplicaciones. Con los SDKs de IMA DAI, las apps realizan una solicitud de transmisión para el video del anuncio y el contenido, ya sea VOD o contenido en vivo. Luego, el SDK devuelve una transmisión de video combinada, de modo que no tengas que administrar el cambio entre el anuncio y el video de contenido en tu app.

Selecciona la solución de DAI que te interesa

Servicio completo Publicación de segmentos

DAI de servicio completo

En esta guía, se muestra cómo integrar el SDK de IMA DAI en una app de reproductor de video. Si deseas ver o seguir una integración de muestra completa, descarga el ejemplo simple de GitHub.

Nota: El SDK de IMA DAI para HTML5 admite transmisiones de HLS y DASH, pero para reproducir cada una se requiere un reproductor multimedia o una extensión diferente, como HLS.js o DASH.js, con diferentes implementaciones.

En esta guía, se explica cómo configurar HLS.js y el SDK de IMA DAI para reproducir una transmisión de HLS, con notas importantes sobre las diferencias de implementación para DASH.

Consulta la app de ejemplo de IMA DASH.js como punto de partida para implementar transmisiones de DAI de DASH con IMA.

Para usar la DAI de IMA, debes tener una cuenta de Ad Manager 360 Advanced. Si tienes una cuenta de Ad Manager, comunícate con tu administrador de cuentas para obtener más detalles. Para obtener información sobre cómo registrarte en Ad Manager, visita el Centro de ayuda de Ad Manager.

Nota: Para obtener información sobre la integración con otras plataformas o sobre el uso de los SDKs de IMA del cliente, consulta SDKs de anuncios multimedia interactivos.

Descripción general de la DAI de IMA

La implementación del SDK de DAI de IMA incluye dos componentes principales, como se muestra en esta guía:

• StreamRequest: Puede ser un objeto VODStreamRequest o un objeto LiveStreamRequest que define una solicitud de transmisión. Las solicitudes de transmisión pueden ser para videos on demand o transmisiones en vivo. Las solicitudes de transmisión en vivo especifican una clave de recurso, mientras que las solicitudes de VOD especifican un ID de CMS y un ID de video. Ambos tipos de solicitudes pueden incluir, de forma opcional, una clave de API necesaria para acceder a las transmisiones especificadas y un código de red de Google Ad Manager para que el SDK de IMA controle los identificadores de anuncios según se especifica en la configuración de Google Ad Manager.
• StreamManager: Objeto que controla las transmisiones de inserción de anuncios dinámicos y las interacciones con el backend de DAI. El administrador de transmisiones también controla los pings de seguimiento y reenvía los eventos de transmisiones y anuncios al publicador.

Requisitos previos

• Tres archivos vacíos
  • dai.html
  • dai.css
  • dai.js
• Python instalado en tu computadora o un servidor web para usar en las pruebas

Inicia un servidor de desarrollo

Dado que el SDK de IMA DAI carga dependencias con el mismo protocolo que la página desde la que se carga, debes usar un servidor web para probar tu app. Una forma rápida de iniciar un servidor de desarrollo local es usar el servidor integrado de Python.

1. Desde una línea de comandos, ejecuta lo siguiente desde el directorio que contiene tu archivo index.html:

   python -m http.server 8000

   Nota: http.server solo está disponible en Python 3.x.

2. En un navegador web, ve a http://localhost:8000/.

   También puedes usar cualquier otro servidor web, como el servidor HTTP de Apache.

Crea un reproductor de video

Primero, modifica dai.html para crear un elemento de video HTML5 y un div para usarlo en el clic. En el siguiente ejemplo, se importa el SDK de IMA DAI. Para obtener más detalles, consulta Cómo importar el SDK de DAI de IMA.

Además, agrega las etiquetas necesarias para cargar los archivos dai.css y dai.js, así como para importar el reproductor de video hls.js. Luego, modifica dai.css para especificar el tamaño y la posición de los elementos de la página. Por último, en dai.js, define variables para contener la información de la solicitud de transmisión, una función initPlayer() para ejecutar cuando se cargue la página y configura el botón de reproducción para solicitar una transmisión cuando se haga clic.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>

dai.html

#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}
dai.css

// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

Para reanudar la reproducción durante las pausas publicitarias pausadas, configura objetos de escucha de eventos para los eventos pause y start del elemento de video para mostrar y ocultar los controles del reproductor.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

Carga el SDK de IMA DAI

A continuación, agrega el framework de IMA con una etiqueta de secuencia de comandos en dai.html, antes de la etiqueta de dai.js.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

Inicializa StreamManager

Para solicitar un conjunto de anuncios, crea un objeto ima.dai.api.StreamManager, que es responsable de solicitar y administrar transmisiones de DAI. El constructor toma un elemento de video y un elemento de IU del anuncio para controlar los clics en el anuncio.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

Realiza una solicitud de transmisión

Define funciones para solicitar transmisiones. Este ejemplo incluye funciones para VOD y transmisiones en vivo, que crean instancias de la clase VODStreamRequest y la clase LiveStreamRequest. Después de obtener la instancia de streamRequest, llama al método streamManager.requestStream() con la instancia de la solicitud de transmisión.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

Ambos métodos de solicitud de transmisión toman una clave de API opcional. Si usas una transmisión protegida, debes crear una clave de autenticación de DAI. Para obtener más detalles, consulta Cómo autenticar solicitudes de transmisión de video por Internet de DAI. Ninguna de las transmisiones de este ejemplo está protegida con una clave de autenticación de DAI, por lo que no se usa apiKey.

Analiza los metadatos de la transmisión

También debes agregar un controlador para escuchar los eventos de metadatos cronometrados y reenviar los eventos a la clase StreamManager para que IMA emita eventos de anuncios durante las pausas publicitarias:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}
dai.js

En esta guía, se usa el reproductor hls.js para la reproducción de transmisiones, pero la implementación de metadatos depende del tipo de reproductor que uses.

Cómo controlar eventos de transmisión

Implementa objetos de escucha de eventos para los eventos de video principales. En este ejemplo, se controlan los eventos LOADED, ERROR, AD_BREAK_STARTED y AD_BREAK_ENDED llamando a una función onStreamEvent(). Esta función controla la carga de transmisiones, los errores de transmisión y la inhabilitación de los controles del reproductor durante la reproducción de anuncios, lo que requiere el SDK de IMA.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}
dai.js

Cuando se carga la transmisión, el reproductor de video carga y reproduce la URL proporcionada con una función loadUrl().

Eso es todo. Ahora solicitas y muestras anuncios con el SDK de DAI de IMA. Para obtener información sobre las funciones más avanzadas del SDK, consulta las otras guías o los ejemplos en GitHub.