Los SDK de IMA facilitan la integración de anuncios multimedia en sus sitios web y aplicaciones. Los SDK de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administra la reproducción de anuncios en tus apps. Con los SDK de IMA del cliente, tú 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 un reproductor de video separado ubicado en la parte superior del reproductor de video de contenido de la app.
En esta guía, se muestra cómo integrar el SDK de IMA en una app simple de reproducción de video. Si quisieras o seguir una integración de muestra completa, descarga la ejemplo simple de GitHub. Si estás interesado en un reproductor HTML5 con SDK preintegrado, consulte la Complemento del SDK de IMA para Video.js.
Descripción general de IMA del cliente
La implementación de IMA del lado del cliente implica cuatro componentes principales del SDK, como se demuestra en este guía:
AdDisplayContainer
: Es un objeto contenedor en el que se renderizan los anuncios.AdsLoader
: Es un objeto que solicita anuncios y controla eventos de respuestas a solicitudes de anuncios. Solo debes crear una instancia de un cargador de anuncios, que puede reutilizarse durante el ciclo de vida de la aplicación.AdsRequest
: 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
: Un objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción y escucha el anuncio eventos 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
Como el SDK de IMA carga las dependencias con el mismo protocolo que la página desde la que se cargan, puedes hacer lo siguiente: necesitas usar un servidor web para probar tu app. La forma más sencilla de comenzar un desarrollo local del servidor es usar el servidor integrado de Python.
- Mediante una línea de comandos, desde el directorio que contiene
tu archivo index.html ejecuta:
python -m http.server 8000
- En un navegador web, ve a
http://localhost:8000/
.
También puedes usar cualquier otro servidor web, como el Servidor HTTP de Apache.
2. Cómo crear un reproductor de video simple
Primero, modifica el archivo index.html para crear un elemento simple de video HTML5 que se encuentre en un ajuste y un botón para activar la reproducción. Además, agrega las etiquetas necesarias para cargar el los archivos style.css y ads.js. A continuación, modifica styles.css para crear el reproductor de video. adaptables para dispositivos móviles. Por último, en ads.js, activa la reproducción de video cuando la se hace clic en el botón correspondiente.
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, abre el archivo index.html en el navegador (a través de la herramienta (servidor), deberías poder ver el elemento de video, y este debe iniciarse al hacer clic en el botón de reproducción.
3. Importa el SDK de IMA
A continuación, agregue el marco de trabajo de IMA con una etiqueta de secuencia de comandos en index.html, antes de la etiqueta de
ads.js
... </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. Adjuntar controladores de páginas y reproductores de video
Para modificar el comportamiento del reproductor de video con JavaScript, agrega controladores de eventos que activen la función siguientes acciones:
- Cuando se termine de cargar la página, inicializa el SDK de IMA.
- Cuando se haga clic en el botón de reproducción del video, cargar anuncios (a menos que ya haya anuncios cargados).
- Cuando cambies el tamaño de la ventana del navegador, actualiza el elemento de video y
adsManager
. dimensiones para que la página sea responsiva para dispositivos móviles
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 tanto anuncios como
relacionados con los anuncios. Este contenedor debe tener el tamaño adecuado para superponerse al elemento de video desde el
en la esquina superior izquierda. La altura y el ancho de los anuncios colocados en este contenedor se establecen según
adsManager
, por lo que no necesitas establecer estos valores de forma manual.
Para implementar este elemento de contenedor de anuncios, primero crea un nuevo elemento div
en el
elemento video-container
. Luego, actualiza el CSS para posicionar el elemento en la parte superior izquierda.
en la esquina de video-element
. Por último, define una variable para el contenedor dentro del
Función initializeIMA()
que se ejecuta cuando se carga la página.
... <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. Cómo inicializar AdsLoader y realizar 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
ima.AdsRequest
objetos asociados con una URL de etiqueta de anuncio especificada. La etiqueta de anuncio utilizada en
Este ejemplo contiene un anuncio previo al video de 10 segundos. Puedes probar esta o cualquier URL de etiqueta de anuncio con el
Inspector de paquetes de video de IMA.
Como práctica recomendada, solo se debe mantener una instancia de ima.AdsLoader
para toda la instancia.
ciclo de vida de una página. Para realizar solicitudes de anuncios adicionales, cree un nuevo ima.AdsRequest
pero volverás a usar el mismo ima.AdsLoader
. Para obtener más información, consulta la
Preguntas frecuentes sobre el SDK de IMA.
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 escuchar eventos de AdsLoader
Cuando los anuncios se cargan correctamente, el ima.AdsLoader
emite un
ADS_MANAGER_LOADED
evento. Analiza el evento que se pasó a la devolución de llamada para inicializar el
AdsManager
. El elemento AdsManager
carga los anuncios individuales como se define en la respuesta al anuncio.
la URL de la etiqueta de recurso.
Además, asegúrate de solucionar cualquier error que pueda ocurrir durante el proceso de carga. Si los anuncios no carga, asegúrate de que continúe la reproducción de contenido multimedia, sin anuncios, para no interferir con el la experiencia del usuario.
ads.jsvar 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 la AdsManager
. Para brindar compatibilidad total
navegadores, esto debería desencadenarse por una interacción del usuario.
... 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. Cómo hacer que AdsManager sea responsivo
Para asegurarse de que los anuncios cambien de tamaño dinámicamente para coincidir con el del reproductor de video, si la pantalla
cambia de tamaño o de orientación, el evento de cambio de tamaño de la ventana debe llamar a adsManager.resize()
.
... 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. Escucha eventos de AdsManager
AdsManager
también activa varios eventos que se deben controlar. Estos eventos se usan
para realizar 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 funcionar como el controlador de errores del
AdsManager
agregando un nuevo controlador de eventos con la misma función de devolución de llamada.
... 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 elemento AdsManager
está listo para insertar un anuncio para mostrar, se activa
CONTENT_PAUSE_REQUESTED
evento. Para controlar este evento, activa una pausa en el
el reproductor de video subyacente. De manera similar, cuando se completa un anuncio, AdsManager
activa
CONTENT_RESUME_REQUESTED
evento. Para controlar este evento, reinicia la reproducción en el
video de contenido subyacente.
... 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(); }
Cómo activar la función de hacer clic para detener en dispositivos móviles
Como la 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 tocar un
el reproductor de video para pausar la reproducción. Para solucionar este problema, el SDK de IMA pasa los clics que no
mediante IMA desde la superposición de anuncios hasta el elemento AdContainer
, donde se pueden
que se encarguen de su administración. Esto no se aplica a los anuncios lineales en navegadores que no son para dispositivos móviles, ya que al hacer 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 la reproducción.
o detener eventos en el video subyacente.
... 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(); } } ...
Cómo activar la reproducción en anuncios no lineales
El elemento AdsManager
detiene el video de contenido cuando un anuncio está listo para reproducirse, pero esta
no tiene en cuenta los anuncios no lineales, en los que el contenido debería seguir reproduciéndose
hasta que se muestre el anuncio. Para admitir anuncios no lineales, escucha que AdsManager
emita el
LOADED
evento. Comprueba si el anuncio es lineal; de no ser así, reanuda la reproducción en la
video.
... 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 está solicitando y mostrando anuncios con el SDK de IMA. Para obtener más información funciones avanzadas del SDK, consulta las otras guías o el muestras en GitHub.