Comenzar

Los SDKs de IMA facilitan la integración de anuncios multimedia en tus sitios web y apps. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios que cumpla con VAST y administrar la reproducción de anuncios en tus apps. Con los SDKs del cliente de IMA, mantienes el control de la reproducción de video de contenido, mientras que el SDK controla la reproducción de anuncios. Los anuncios se reproducen en un reproductor de video independiente ubicado sobre el reproductor de video de contenido de la app.

En esta guía, se muestra cómo integrar el SDK de IMA en una app de reproductor de video simple. Si deseas ver o seguir una integración de muestra completa, descarga el ejemplo simple de GitHub. Si te interesa un reproductor HTML5 con el SDK preintegrado, consulta el complemento del SDK de IMA para Video.js.

Descripción general del IMA del cliente

La implementación de IMA del cliente implica cuatro componentes principales del SDK, que se muestran en esta guía:

  • AdDisplayContainer: Un objeto contenedor que especifica dónde la IMA renderiza los elementos de la IU del anuncio y mide la visibilidad, incluida la Vista activa y la medición abierta.
  • AdsLoader: Es un objeto que solicita anuncios y controla eventos de las respuestas de solicitudes de anuncios. Solo debes crear una instancia de un cargador de anuncios, que se puede reutilizar durante toda la vida de la aplicación.
  • AdsRequest: Es un objeto que define una solicitud de anuncios. Las solicitudes de anuncios especifican la URL de la etiqueta de anuncio de VAST, así como parámetros adicionales, como las dimensiones del anuncio.
  • AdsManager: Es un objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción de anuncios y escucha los eventos de anuncios que activa el SDK.

Requisitos previos

Necesitarás lo siguiente antes de comenzar:

  • Tres archivos vacíos:
    • index.html
    • style.css
    • ads.js
  • Python instalado en tu computadora o un servidor web para usarlo en las pruebas

1. Cómo iniciar un servidor de desarrollo

Dado que el SDK de IMA carga dependencias a través del mismo protocolo que la página desde la que se carga, debes usar un servidor web para probar tu app. La forma más sencilla de iniciar un servidor de desarrollo local es usar el servidor integrado de Python.

  1. En una línea de comandos, desde el directorio que contiene tu archivo index.html, ejecuta lo siguiente: 
      python -m http.server 8000
  2. En un navegador web, ve a http://localhost:8000/.

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

2. Crea un reproductor de video simple

Primero, modifica index.html para crear un elemento de video HTML5 simple, contenido en un elemento de unión y un botón para activar la reproducción. También agrega las etiquetas necesarias para cargar los archivos style.css y ads.js. Luego, modifica styles.css para que el reproductor de video sea responsivo para dispositivos móviles. Por último, en ads.js, activa la reproducción de video cuando se hace clic en el botón de reproducción.

index.html 
<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
 style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
 ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

Después de completar este paso, cuando abras index.html en tu navegador (a través de tu servidor de desarrollo), deberías poder ver el elemento de video, y este debería comenzar cuando hagas clic en el botón de reproducción.

3. Importa el SDK de IMA

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

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Cómo adjuntar controladores de página y reproductor de video

Para modificar el comportamiento del reproductor de video con JavaScript, agrega controladores de eventos que activen las siguientes acciones:

  • Cuando la página termine de cargarse, inicializa el SDK de IMA.
  • Cuando se hace clic en el botón de reproducción del video, se cargan los anuncios (a menos que ya haya anuncios cargados).
  • Cuando se cambie el tamaño de la ventana del navegador, actualiza el elemento de video y las dimensiones de adsManager para que la página sea responsiva para dispositivos móviles.
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. Crea el contenedor de anuncios

En la mayoría de los navegadores, el SDK de IMA usa un elemento de contenedor de anuncios exclusivo para mostrar anuncios y elementos de la IU relacionados con los anuncios. El tamaño de este contenedor debe ser suficiente para superponer el elemento de video desde la esquina superior izquierda. El objeto adsManager establece la altura y el ancho de los anuncios que se colocan en este contenedor, por lo que no es necesario que configures estos valores de forma manual.

Para implementar este elemento de contenedor de anuncios, primero crea un div nuevo dentro del elemento video-container. Luego, actualiza el CSS para posicionar el elemento en la esquina superior izquierda del video-element. Por último, define una variable para el contenedor dentro de la función initializeIMA() que se ejecuta cuando se carga la página.

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
 style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
 ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. Inicializa AdsLoader y realiza una solicitud de anuncios

Para solicitar un conjunto de anuncios, crea una instancia de ima.AdsLoader. Esta instancia toma un objeto AdDisplayContainer como entrada y se puede usar para procesar objetos ima.AdsRequest asociados con una URL de etiqueta de anuncio especificada. La etiqueta de anuncio que se usa en este ejemplo contiene un anuncio previo al video de 10 segundos. Puedes probar esta URL de etiqueta de anuncio o cualquier otra con el Inspector de paquetes de video de IMA.

Como práctica recomendada, mantén solo una instancia de ima.AdsLoader para todo el ciclo de vida de una página. Para realizar solicitudes de anuncios adicionales, crea un objeto ima.AdsRequest nuevo, pero vuelve a usar el mismo ima.AdsLoader. Para obtener más información, consulta las Preguntas frecuentes del SDK de IMA.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
      'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Cómo detectar eventos de AdsLoader

Cuando los anuncios se cargan correctamente, ima.AdsLoader emite un evento ADS_MANAGER_LOADED. Analiza el evento que se pasa a la devolución de llamada para inicializar el objeto AdsManager. AdsManager carga los anuncios individuales según lo define la respuesta a la URL de la etiqueta de anuncio.

Además, asegúrate de controlar los errores que puedan ocurrir durante el proceso de carga. Si los anuncios no se cargan, asegúrate de que la reproducción de contenido multimedia continúe, sin anuncios, para no interferir en la experiencia del usuario.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Inicia AdsManager

Para iniciar la reproducción de anuncios, debes iniciar AdsManager. Para admitir por completo los navegadores para dispositivos móviles, esto debe activarse mediante una interacción del usuario.

ads.js 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Haz que AdsManager sea responsivo

Para garantizar que los anuncios cambien de tamaño de forma dinámica para que coincidan con el tamaño del reproductor de video, si la pantalla cambia de tamaño o orientación, el evento de cambio de tamaño de la ventana debe llamar a adsManager.resize().

ads.js 
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. Detecta eventos de AdsManager

AdsManager también activa varios eventos que se deben controlar. Estos eventos se usan para hacer un seguimiento de los cambios de estado, activar la reproducción y la pausa en el video de contenido, y registrar errores.

Maneja los errores

El controlador de errores creado para AdsLoader puede servir como controlador de errores para AdsManager si se agrega un nuevo controlador de eventos con la misma función de devolución de llamada.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

Cómo activar eventos de reproducción y pausa

Cuando el AdsManager está listo para insertar un anuncio para su visualización, activa el evento CONTENT_PAUSE_REQUESTED. Para controlar este evento, activa una pausa en el reproductor de video subyacente. De manera similar, cuando se completa un anuncio, AdsManager activa el evento CONTENT_RESUME_REQUESTED. Para controlar este evento, reinicia la reproducción en el video de contenido subyacente.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

Activación de la función hacer clic para pausar en dispositivos móviles

Como AdContainer se superpone al elemento de video, los usuarios no pueden interactuar directamente con el reproductor subyacente. Esto puede confundir a los usuarios de dispositivos móviles, que esperan poder presionar un reproductor de video para pausar la reproducción. Para solucionar este problema, el SDK de IMA pasa los clics que IMA no controla desde la superposición de anuncios al elemento AdContainer, donde se pueden controlar. Esto no se aplica a los anuncios lineales en navegadores que no son para dispositivos móviles, ya que, cuando se hace clic en el anuncio, se abre el vínculo de clic.

Para implementar la función de hacer clic para pausar, agrega un controlador de clics a AdContainer y activa eventos de reproducción o pausa en el video subyacente.

ads.js 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Activación de la reproducción en anuncios no lineales

AdsManager pausa el video de contenido cuando un anuncio está listo para reproducirse, pero este comportamiento no tiene en cuenta los anuncios no lineales, en los que el contenido debe seguir reproduciéndose mientras se muestra el anuncio. Para admitir anuncios no lineales, escucha el AdsManager para que emita el evento LOADED. Luego, verifica si el anuncio es lineal y, de no ser así, reanuda la reproducción en el elemento de video.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

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