Para analizar nuestros productos y proporcionar comentarios sobre ellos, únete al canal oficial de Discord de Ad Manager en el servidor de la Comunidad de Publicidad y Medición de Google.

Se usó la API de Cloud Translation para traducir esta página.

Configura el SDK de IMA

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 del cliente de IMA, mantienes el control de la reproducción de videos 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 ejemplo 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 del SDK del cliente de IMA implica cuatro componentes principales del SDK, que se demuestran en esta guía:

AdDisplayContainer: Es un objeto contenedor que especifica dónde IMA renderiza los elementos de la IU del anuncio y mide la visibilidad, incluidos Vista activa y Open Measurement.
AdsLoader: Es un objeto que solicita anuncios y controla eventos de respuestas a solicitudes de anuncios. Solo debes crear una instancia del cargador de anuncios, que se puede reutilizar durante la vida útil 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: 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 usar en las pruebas

1. Inicia un servidor de desarrollo

Dado que el SDK de IMA carga dependencias con el 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.

Desde la 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.
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 ajuste y un botón para activar la reproducción. En el siguiente ejemplo, se importa el SDK de IMA y se configura el elemento contenedor AdDisplayContainer. Para obtener más detalles, consulta los pasos Importa el SDK de IMA y Crea el contenedor de anuncios , respectivamente.

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>
index.html

#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}style.css

let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});ads.js

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 en dispositivos móviles. Por último, en ads.js, declara tus variables y activa la reproducción de video cuando hagas clic en el botón de reproducción.

Ten en cuenta que el fragmento de código ads.js contiene una llamada a setUpIMA(), que se define en la sección Inicializa AdsLoader y realiza una solicitud de anuncios .

3. Importa el SDK de IMA

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>index.html

En la mayoría de los navegadores, el SDK de IMA usa un elemento de contenedor de anuncios dedicado para mostrar tanto los anuncios como los elementos de la IU relacionados con los anuncios. Este contenedor debe tener el tamaño adecuado para superponerse al elemento de video desde la esquina superior izquierda. El objeto adsManager establece la altura y el ancho de los anuncios colocados en este contenedor, por lo que no es necesario que establezcas estos valores de forma manual.

Para implementar este elemento contenedor de anuncios, primero crea un nuevo div dentro del elemento video-container. Luego, actualiza el CSS para colocar el elemento en la esquina superior izquierda de video-element. Por último, agrega la función createAdDisplayContainer() para crear el objeto AdDisplayContainer con el nuevo contenedor de anuncios div.

<div id="adContainer"></div>index.html

#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}style.css

/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}ads.js

5. Inicializa AdsLoader y realiza una solicitud de anuncios

Para solicitar anuncios, crea una instancia de AdsLoader. El constructor AdsLoader toma un objeto AdDisplayContainer como entrada y se puede usar para procesar objetos 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 o cualquier otra URL de etiqueta de anuncio con el Inspector de paquetes de video de IMA.

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

Usa AdsLoader.addEventListener para escuchar y responder a los eventos de error y de carga de anuncios. Detecta los siguientes eventos:

ADS_MANAGER_LOADED
AD_ERROR

Para crear los objetos de escucha onAdsManagerLoaded() y onAdError(), consulta el siguiente ejemplo:

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}ads.js

6. Cómo responder a los eventos de AdsLoader

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

Asegúrate de controlar los errores que se produzcan durante el proceso de carga. Si no se cargan los anuncios, asegúrate de que la reproducción de contenido multimedia continúe sin anuncios para evitar interferir en la visualización del contenido por parte del usuario.

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}ads.js

Para obtener más detalles sobre los objetos de escucha establecidos en la función onAdsManagerLoaded(), consulta las siguientes subsecciones:

Cómo controlar errores `AdsManager`

El controlador de errores creado para AdsLoader también puede servir como controlador de errores para AdsManager. Observa el controlador de eventos que reutiliza la función onAdError().

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

Cómo controlar eventos de reproducción y pausa

Cuando el objeto AdsManager está listo para insertar un anuncio para su visualización, activa el evento CONTENT_PAUSE_REQUESTED. Controla este evento activando una pausa en el reproductor de video subyacente. Del mismo modo, cuando se completa un anuncio, AdsManager activa el evento CONTENT_RESUME_REQUESTED. Controla este evento reiniciando la reproducción del video de contenido subyacente.

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);ads.js

Para obtener las definiciones de las funciones onContentPauseRequested() y onContentResumeRequested(), consulta el siguiente ejemplo:

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}ads.js

Cómo controlar la reproducción de contenido durante los anuncios no lineales

El método 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 se sigue reproduciendo mientras se muestra el anuncio.

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);ads.js

Para admitir anuncios no lineales, escucha el evento AdsManager para emitir el evento LOADED. Comprueba si el anuncio es lineal y, si no lo es, reanuda la reproducción en el elemento de video.

Para ver la definición de la función onAdLoaded(), consulta el siguiente ejemplo.

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}ads.js

7. Cómo activar la función de hacer clic para pausar en dispositivos móviles

Dado que 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 del anuncio 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 la función de controlador de clics adContainerClick() llamada en el objeto de escucha de carga de la ventana.

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}ads.js

8. Inicia AdsManager

Para iniciar la reproducción del anuncio, inicia y comienza el AdsManager. Para admitir completamente los navegadores para dispositivos móviles, en los que no puedes reproducir anuncios automáticamente, activa la reproducción de anuncios a partir de las interacciones del usuario con la página, como hacer clic en el botón de reproducción.

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}ads.js

9. Admite el cambio de tamaño del reproductor

Para que los anuncios cambien de tamaño de forma dinámica y coincidan con el tamaño de un reproductor de video, o para que coincidan con los cambios en la orientación de la pantalla, llama a adsManager.resize() en respuesta a los eventos de cambio de tamaño de la ventana.

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

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