Cómo comenzar a usar el SDK de IMA de DAI

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 de DAI de IMA, las apps realizan una solicitud de transmisión de anuncios y videos de contenido, ya sea VOD o contenido en vivo. Luego, el SDK muestra una transmisión de video combinada para que no tengas que administrar el cambio entre el video de anuncios y el de contenido dentro de tu app.

Selecciona la solución de DAI que te interesa

Servicio completo Publicación de pods

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 simple. Si deseas ver o seguir una integración de ejemplo completa, descarga BasicExample desde GitHub.

Nota: El SDK de DAI de IMA para Android admite transmisiones HLS y DASH.

En esta guía, se explica cómo configurar exoplayer y el SDK de IMA DAI para reproducir una transmisión HLS. Para ver un ejemplo de un reproductor de video que admite transmisiones HLS y DASH, consulta nuestro ejemplo avanzado.

Para usar la inserción de anuncios dinámicos de IMA, debes tener una cuenta de Ad Manager 360 avanzada. 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.

Punto clave: La extensión IMA de ExoPlayer ofrece una forma optimizada de usar la DAI de IMA en Android. Consulta la guía de la extensión de IMA de ExoPlayer y ExoPlayerExample en GitHub para obtener más información.

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

Descripción general de la DAI de IMA

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

• StreamDisplayContainer: Es un objeto contenedor que se encuentra sobre el elemento de reproducción de video y contiene los elementos de la IU del anuncio.
• AdsLoader: Es un objeto que solicita transmisiones y controla los eventos activados por los objetos de respuesta de solicitudes de transmisión. Solo debes crear una instancia de un cargador de anuncios, que se puede volver a usar durante la vida útil de la aplicación.
• StreamRequest: Es un objeto que define una solicitud de transmisión. Las solicitudes de transmisión pueden ser de video on demand o de transmisiones en vivo. Las solicitudes especifican un ID de contenido, así como una clave de API o un token de autenticación y otros parámetros.
• StreamManager: Un 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 transmisión y de anuncios al publicador.

Requisitos previos

• Android Studio
• App de reproductor de video de ejemplo para la integración del SDK

Descarga y ejecuta la app de reproductor de video de ejemplo

La app de ejemplo proporciona un reproductor de video en funcionamiento que reproduce videos HLS. Úsalo como punto de partida para integrar las funciones de DAI del SDK de IMA.

1. Descarga la app de reproductor de video de muestra y extráela.

2. Inicia Android Studio y selecciona Open an existing Android Studio project o, si Android Studio ya está en ejecución, selecciona File > New > Import Project. Luego, elige SampleVideoPlayer/build.gradle.

3. Para ejecutar una sincronización de Gradle, selecciona Tools > Android > Sync Project with Gradle Files.

4. Asegúrate de que la app del reproductor se compile y ejecute en un dispositivo Android físico o en un dispositivo virtual de Android con Run > Run "app". Es normal que la transmisión de video tarde unos minutos en cargarse antes de reproducirse.

Sugerencia: Si recién te inicias en el desarrollo de aplicaciones para Android, consulta los tutotiales sobre depuración mediante USB y uso de dispositivos virtuales. Debes hacer una de esas dos acciones para ejecutar tu nueva app y ver cómo se ve.

Examina el reproductor de video de ejemplo

El reproductor de video de ejemplo aún no contiene ningún código de integración del SDK de IMA DAI. La app de ejemplo consta de dos partes principales:

1. samplevideoplayer/SampleVideoPlayer.java: Es un reproductor HLS basado en ExoPlayer que sirve como base para la integración de DAI de IMA.

2. videoplayerapp/MyActivity.java: Esta actividad crea el reproductor de video y le pasa un Context y un SimpleExoPlayerView.

Agrega el SDK de IMA DAI a la app del reproductor

También debes incluir una referencia al SDK de IMA DAI. En Android Studio, agrega lo siguiente a tu archivo build.gradle a nivel de la aplicación, ubicado en app/build.gradle:

repositories {
  google()
  mavenCentral()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.35.1'
}

Punto clave: En este punto, tu app debería compilarse y ejecutarse, aunque aún no hayas agregado elementos de la IU ni código para solicitar y mostrar anuncios.

Integra el SDK de IMA DAI

1. Crea una clase nueva llamada SampleAdsWrapper en el paquete videoplayerapp (en app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) para unir el SampleVideoPlayer existente y agregar lógica que implemente la DAI de IMA. Para ello, primero debes crear un AdsLoader que se use para solicitar anuncios a los servidores de anuncios.

   Importante: Para reducir la latencia que causa IMA, es importante crear el AdsLoader en cuanto se inicia la app. Esto maximiza el tiempo que tiene IMA para cargar los recursos necesarios antes de la primera solicitud de transmisión. También debes volver a usar una sola instancia de AdsLoader para evitar la latencia adicional que se produce cuando la vuelves a crear.

   videoplayerapp/SampleAdsWrapper.java

   package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
   
   import android.annotation.TargetApi;
   import android.content.Context;
   import android.os.Build;
   import android.view.ViewGroup;
   import android.webkit.WebView;
   
   import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.AdsLoader;
   import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
   import com.google.ads.interactivemedia.v3.api.CuePoint;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
   import com.google.ads.interactivemedia.v3.api.StreamManager;
   import com.google.ads.interactivemedia.v3.api.StreamRequest;
   import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
   import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
   
   import java.util.ArrayList;
   import java.util.HashMap;
   import java.util.List;
   
   public class SampleAdsWrapper implements AdEvent.AdEventListener,
           AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
   
       // Livestream asset key.
       private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";
   
       // VOD content source and video IDs.
       private static final String TEST_CONTENT_SOURCE_ID = "2548831";
       private static final String TEST_VIDEO_ID = "tears-of-steel";
   
       private static final String PLAYER_TYPE = "DAISamplePlayer";
   
       /**
        * Log interface, so you can output the log commands to the UI or similar.
        */
       public interface Logger {
           void log(String logMessage);
       }
   
       private ImaSdkFactory sdkFactory;
       private AdsLoader adsLoader;
       private StreamDisplayContainer displayContainer;
       private StreamManager streamManager;
       private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
   
       private SampleVideoPlayer videoPlayer;
       private Context context;
       private ViewGroup adUiContainer;
   
       private String fallbackUrl;
       private Logger logger;
   
       public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer,
                               ViewGroup adUiContainer) {
           this.videoPlayer = videoPlayer;
           this.context = context;
           this.adUiContainer = adUiContainer;
           sdkFactory = ImaSdkFactory.getInstance();
           playerCallbacks = new ArrayList<>();
           createAdsLoader();
           displayContainer = sdkFactory.createStreamDisplayContainer(
               this.adUiContainer,
               videoStreamPlayer
           );
       }
   
       private void createAdsLoader() {
           ImaSdkSettings settings = new ImaSdkSettings();
           adsLoader = sdkFactory.createAdsLoader(context);
       }
   
       public void requestAndPlayAds() {
           adsLoader.addAdErrorListener(this);
           adsLoader.addAdsLoadedListener(this);
           adsLoader.requestStream(buildStreamRequest());
       }
   }
   

2. Agrega un método buildStreamRequest() a AdsLoader para que pueda solicitar una transmisión con anuncios. Puede ser una transmisión en vivo con anuncios (configurada de forma predeterminada) o una transmisión de video on demand(VOD) que reproduce contenido pregrabado con anuncios. Para habilitar la transmisión de VOD, comenta la solicitud de transmisión en vivo y quita el comentario de la solicitud de transmisión de VOD.

   Para trabajar con la DAI, un reproductor debe pasar eventos ID3 para las transmisiones en vivo a los SDK de IMA DAI. En el siguiente código de muestra, el método callback.onUserTextReceived() hace lo siguiente:

   videoplayerapp/SampleAdsWrapper.java

   private StreamRequest buildStreamRequest() {
       VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
       videoPlayer.setSampleVideoPlayerCallback(
               new SampleVideoPlayer.SampleVideoPlayerCallback() {
                   @Override
                   public void onUserTextReceived(String userText) {
                       for (VideoStreamPlayer.VideoStreamPlayerCallback callback :
                               playerCallbacks) {
                           callback.onUserTextReceived(userText);
                       }
                   }
   
                   @Override
                   public void onSeek(int windowIndex, long positionMs) {
                       // See if you would seek past an ad, and if so, jump back to it.
                       long newSeekPositionMs = positionMs;
                       if (streamManager != null) {
                           CuePoint prevCuePoint  =
                                   streamManager.getPreviousCuePointForStreamTime(positionMs / 1000);
                           if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
                               newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000);
                           }
                       }
                       videoPlayer.seekTo(windowIndex, newSeekPositionMs);
                   }
   
                   @Override
                   public void onContentComplete() {
                       for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
                           callback.onContentComplete();
                       }
                   }
   
                   @Override
                   public void onPause() {
                       for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
                           callback.onPause();
                       }
                   }
   
                   @Override
                   public void onResume() {
                       for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
                           callback.onResume();
                       }
                   }
   
                   @Override
                   public void onVolumeChanged(int percentage) {
                       for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
                           callback.onVolumeChanged(percentage);
                       }
                   }
               });
   
       // Livestream request.
       StreamRequest request = sdkFactory.createLiveStreamRequest(
               TEST_ASSET_KEY, null, displayContainer);
   
       // VOD request. Comment the createLiveStreamRequest() line above and uncomment this
       // createVodStreamRequest() below to switch from a livestream to a VOD stream.
       // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID,
       //        TEST_VIDEO_ID, null, displayContainer);
       return request;
   }
   

3. También necesitas un VideoStreamPlayer para reproducir la transmisión, por lo que debes agregar un método createVideoStreamPlayer(), que crea una clase anónima que implementa VideoStreamPlayer.

   videoplayerapp/SampleAdsWrapper.java

   private VideoStreamPlayer createVideoStreamPlayer() {
       VideoStreamPlayer player = new VideoStreamPlayer() {
           @Override
           public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
               videoPlayer.setStreamUrl(url);
               videoPlayer.play();
           }
   
           @Override
           public void addCallback(
               VideoStreamPlayerCallback videoStreamPlayerCallback) {
                   playerCallbacks.add(videoStreamPlayerCallback);
           }
   
           @Override
           public void removeCallback(
               VideoStreamPlayerCallback videoStreamPlayerCallback) {
                   playerCallbacks.remove(videoStreamPlayerCallback);
           }
   
           @Override
           public void onAdBreakStarted() {
               // Disable player controls.
               videoPlayer.enableControls(false);
               log("Ad Break Started\n");
           }
   
           @Override
           public void onAdBreakEnded() {
               // Re-enable player controls.
               videoPlayer.enableControls(true);
               log("Ad Break Ended\n");
           }
   
           @Override
           public VideoProgressUpdate getContentProgress() {
               return new VideoProgressUpdate(videoPlayer.getCurrentPosition(),
                       videoPlayer.getDuration());
           }
   
           @Override
           public int getVolume() {
               return videoPlayer.getVolume();
           }
       };
       return player;
   }
   

4. Implementa los objetos de escucha necesarios y agrega compatibilidad con el manejo de errores.

   Ten en cuenta la implementación de AdErrorListener, ya que llama a una URL de resguardo si los anuncios no se reproducen. Dado que el contenido y los anuncios se encuentran en una transmisión, debes estar listo para llamar a una transmisión de resguardo si la transmisión de DAI encuentra un error.

   videoplayerapp/SampleAdsWrapper.java

   /** AdErrorListener implementation **/
   @Override
   public void onAdError(AdErrorEvent event) {
       // play fallback URL.
       videoPlayer.setStreamUrl(fallbackUrl);
       videoPlayer.enableControls(true);
       videoPlayer.play();
   }
   
   /** AdEventListener implementation **/
   @Override
   public void onAdEvent(AdEvent event) {
       switch (event.getType()) {
           case AD_PROGRESS:
               // Do nothing or else log are filled by these messages.
               break;
           default:
               log(String.format("Event: %s\n", event.getType()));
               break;
       }
   }
   
   /** AdsLoadedListener implementation **/
   @Override
   public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
       streamManager = event.getStreamManager();
       streamManager.addAdErrorListener(this);
       streamManager.addAdEventListener(this);
       streamManager.init();
   }
   
   /** Sets fallback URL in case ads stream fails. **/
   void setFallbackUrl(String url) {
       fallbackUrl = url;
   }
   

5. Agrega el código para el registro.

   videoplayerapp/SampleAdsWrapper.java

   /** Sets logger for displaying events to screen. Optional. **/
   void setLogger(Logger logger) {
       this.logger = logger;
   }
   
   private void log(String message) {
       if (logger != null) {
           logger.log(message);
       }
   }
   

6. Modifica MyActivity en videoplayerapp para crear una instancia de SampleAdsWrapper y llamarla.

   videoplayerapp/MyActivity.java

   import android.view.ViewGroup;
   import android.widget.ScrollView;
   ...
   public class MyActivity extends AppCompatActivity {
   ...
       @Override
       protected void onCreate(Bundle savedInstanceState) {
           super.onCreate(savedInstanceState);
           setContentView(R.layout.activity_my);
           View rootView = findViewById(R.id.videoLayout);
           videoPlayer = new SampleVideoPlayer(rootView.getContext(),
                   (SimpleExoPlayerView) rootView.findViewById(R.id.playerView));
           videoPlayer.enableControls(false);
   
           final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer,
               (ViewGroup) rootView.findViewById(R.id.adUiContainer));
           sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
   
           final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll);
           final TextView textView = (TextView) findViewById(R.id.logText);
   
           sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() {
               @Override
               public void log(String logMessage) {
                   Log.i(APP_LOG_TAG, logMessage);
                   if (textView != null) {
                       textView.append(logMessage);
                   }
                   if (scrollView != null) {
                       scrollView.post(new Runnable() {
                           @Override
                           public void run() {
                               scrollView.fullScroll(View.FOCUS_DOWN);
                           }
                       });
                   }
               }
           });
   
           playButton = (ImageButton) rootView.findViewById(R.id.playButton);
           // Set up play button listener to play video then hide play button.
           playButton.setOnClickListener(new View.OnClickListener() {
               @Override
               public void onClick(View view) {
                   sampleAdsWrapper.requestAndPlayAds();
                   playButton.setVisibility(View.GONE);
               }
           });
       }
   ...
   }
   

7. Modifica el archivo de diseño activity_my.xml de la actividad para agregar elementos de la IU para el registro.

   res/layout/activity_my.xml

   ...
       <TextView
           android:id="@+id/playerDescription"
           android:text="@string/video_description"
           android:textAlignment="center"
           android:gravity="center_horizontal"
           android:layout_width="match_parent"
           android:layout_height="0dp"
           android:layout_weight="0.1"
           android:textSize="@dimen/font_size" />
       <!-- UI element for viewing SDK event log -->
       <ScrollView
           android:id="@+id/logScroll"
           android:layout_width="match_parent"
           android:layout_height="0dp"
           android:layout_weight="0.5"
           android:padding="5dp"
           android:background="#DDDDDD">
   
           <TextView
               android:id="@+id/logText"
               android:layout_width="match_parent"
               android:layout_height="wrap_content">
           </TextView>
       </ScrollView>
   ...
   

¡Felicitaciones! Ahora solicitas y muestras anuncios de video en tu app para Android. Para ajustar tu implementación, consulta Favoritos, Snapback y la documentación de la API.

Solución de problemas

Si tienes problemas para reproducir un anuncio de video, intenta descargar el BasicExample completo. Si funciona correctamente en BasicExample, es probable que haya un problema con el código de integración de IMA de tu app.

Si los problemas persisten, visita el foro del SDK de IMA.