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 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
: 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 usar en las pruebas
1. Cómo iniciar 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.
- En una línea de comandos, desde el directorio que contiene tu archivo index.html, ejecuta lo siguiente:
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. 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. En el siguiente ejemplo, se importa el SDK de IMA y se configura el elemento del contenedor AdDisplayContainer
. Para obtener más detalles, consulta los pasos
Importa el SDK de IMA
y
Crea el contenedor de anuncios
.
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, 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 framework de IMA con una etiqueta de secuencia de comandos en index.html, antes de la etiqueta para ads.js
.
4. 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, agrega la función createAdDisplayContainer()
para crear el objeto AdDisplayContainer
con el nuevo contenedor de anuncios div
.
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 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 AdsLoader
para 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.
Escucha y responde a los eventos de error y carga de anuncios con AdsLoader.addEventListener
.
Escucha los siguientes eventos:
ADS_MANAGER_LOADED
AD_ERROR
Para crear los objetos de escucha onAdsManagerLoaded()
y onAdError()
, consulta el siguiente ejemplo:
6. Cómo responder a eventos de AdsLoader
Cuando AdsLoader
carga anuncios de forma correcta, emite un evento ADS_MANAGER_LOADED
. Analiza el evento que se pasó 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.
Asegúrate de controlar los errores que se produzcan 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 evitar interferir en la visualización del contenido por parte del usuario.
Para obtener más detalles sobre los objetos de escucha establecidos en la función onAdsManagerLoaded()
, consulta las siguientes sub secciones:
Controla los errores AdsManager
El controlador de errores creado para AdsLoader
también puede servir como controlador de errores para AdsManager
. Consulta el controlador de eventos que reutiliza la función onAdError()
.
Cómo controlar eventos de reproducción y pausa
Cuando AdsManager
está listo para insertar un anuncio para mostrarlo, 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.
Para ver las definiciones de las funciones onContentPauseRequested()
y onContentResumeRequested()
, consulta el siguiente ejemplo:
Controla la reproducción de contenido durante los anuncios no lineales
AdsManager
detiene 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.
Para admitir anuncios no lineales, escucha el AdsManager
para que emita el evento LOADED
. Comprueba si el anuncio es lineal y, de lo contrario, reanuda la reproducción en el elemento de video.
Para ver la definición de la función onAdLoaded()
, consulta el siguiente ejemplo.
7. Activa la función de 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 pausar con un clic, agrega la función de controlador de clics adContainerClick()
que se llama en el objeto de escucha de carga de ventana.
8. Inicia AdsManager
Para iniciar la reproducción de anuncios, inicia y comienza el AdsManager
. Para admitir por completo 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.
9. Cómo admitir 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.
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.