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

Configura el SDK de IMA para la 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 contenido dentro de tu app.

Selecciona la solución de DAI que te interesa

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.

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 de transmisión en vivo especifican una clave de activo, mientras que las solicitudes de VOD especifican un ID de CMS y un ID de video. De manera opcional, ambos tipos de solicitudes pueden incluir una clave de API necesaria para acceder a transmisiones específicas y un código de red de Google Ad Manager para que el SDK de IMA controle los identificadores de anuncios, como se especifica en la configuración de Google Ad Manager.
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.

Descarga la app de reproductor de video de muestra y extráela.
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.
Para ejecutar una sincronización de Gradle, selecciona Tools > Android > Sync Project with Gradle Files.
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 demore unos minutos en cargarse antes de reproducirse.

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:

samplevideoplayer/SampleVideoPlayer.java: Es un reproductor HLS basado en ExoPlayer que sirve como base para la integración de DAI de IMA.
videoplayerapp/MyActivity.java: Esta actividad crea el reproductor de video y le pasa un Context y un media3.ui.PlayerView.

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 {
    def media3_version = "1.5.1"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation "androidx.media3:media3-ui:$media3_version"
    implementation "androidx.media3:media3-exoplayer:$media3_version"
    implementation "androidx.media3:media3-exoplayer-hls:$media3_version"
    implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
    implementation 'androidx.mediarouter:mediarouter:1.7.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.36.0'build.gradle

Integra el SDK de IMA DAI

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 la transmisión de DAI.

Este fragmento incluye parámetros de muestra para HLS y DASH, transmisiones en vivo y VOD. Para establecer qué transmisión se está reproduciendo, actualiza la variable CONTENT_TYPE.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.content.Context;
import android.view.ViewGroup;
import android.webkit.WebView;
import androidx.annotation.Nullable;
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.StreamDisplayContainer;
import com.google.ads.interactivemedia.v3.api.StreamManager;
import com.google.ads.interactivemedia.v3.api.StreamRequest;
import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
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 com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

/** This class adds ad-serving support to Sample HlsVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Live HLS stream asset key.
  private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  // Live DASH stream asset key.
  private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";

  // VOD HLS content source and video IDs.
  private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
  private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";

  // VOD DASH content source and video IDs.
  private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
  private static final String TEST_DASH_VIDEO_ID = "tos-dash";

  private static final String NETWORK_CODE = "21775744923";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  private enum ContentType {
    LIVE_HLS,
    LIVE_DASH,
    VOD_HLS,
    VOD_DASH,
  }

  // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
  private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {
    void log(String logMessage);
  }

  private final ImaSdkFactory sdkFactory;
  private AdsLoader adsLoader;
  private StreamManager streamManager;
  private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;

  private final SampleVideoPlayer videoPlayer;
  private final Context context;
  private final ViewGroup adUiContainer;

  private String fallbackUrl;
  private Logger logger;

  /**
   * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
   *
   * @param context the app's context.
   * @param videoPlayer underlying HLS video player.
   * @param adUiContainer ViewGroup in which to display the ad's UI.
   */
  public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
    this.videoPlayer = videoPlayer;
    this.context = context;
    this.adUiContainer = adUiContainer;
    sdkFactory = ImaSdkFactory.getInstance();
    playerCallbacks = new ArrayList<>();
    createAdsLoader();
  }

  private void enableWebViewDebugging() {
    WebView.setWebContentsDebuggingEnabled(true);
  }

  private void createAdsLoader() {
    enableWebViewDebugging();
    VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
    StreamDisplayContainer displayContainer =
        ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
    videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
    adsLoader =
        sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
  }

  public void requestAndPlayAds() {
    adsLoader.addAdErrorListener(this);
    adsLoader.addAdsLoadedListener(this);
    adsLoader.requestStream(buildStreamRequest());
  }
SampleAdsWrapper.java

Crea un método auxiliar createSampleVideoPlayerCallback() para controlar la creación de una instancia de interfaz SampleVideoPlayerCallback que extiende VideoStreamPlayer.VideoStreamPlayerCallback.

Para trabajar con la DAI, el reproductor debe pasar eventos ID3 para las transmisiones en vivo al SDK de IMA DAI. El método callback.onUserTextReceived() hace esto en el siguiente código de muestra.

private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
  return new 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 we would seek past an ad, and if so, jump back to it.
      long newSeekPositionMs = positionMs;
      if (streamManager != null) {
        CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
        if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
          newSeekPositionMs = prevCuePoint.getStartTimeMs();
        }
      }
      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);
      }
    }
  };
}
SampleAdsWrapper.java

Agrega un método buildStreamRequest() para crear el SteamRequest. Este método cambia entre diferentes transmisiones según la forma en que configures la variable CONTENT_TYPE. La transmisión predeterminada que se usa en esta guía es la transmisión HLS de VOD de muestra de IMA.

@Nullable
private StreamRequest buildStreamRequest() {
  StreamRequest request;
  switch (CONTENT_TYPE) {
    case LIVE_HLS:
      // Live HLS stream request.
      return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
    case LIVE_DASH:
      // Live DASH stream request.
      return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
    case VOD_HLS:
      // VOD HLS request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.HLS);
      return request;
    case VOD_DASH:
      // VOD DASH request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.DASH);
      return request;
  }
  // Content type not selected.
  return null;
}
SampleAdsWrapper.java

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.

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }

    @Override
    public void pause() {
      // Pause player.
      videoPlayer.pause();
    }

    @Override
    public void resume() {
      // Resume player.
      videoPlayer.play();
    }

    @Override
    public int getVolume() {
      // Make the video player play at the current device volume.
      return 100;
    }

    @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.
      if (videoPlayer != null) {
        videoPlayer.enableControls(true);
      }
      log("Ad Break Ended\n");
    }

    @Override
    public void onAdPeriodStarted() {
      log("Ad Period Started\n");
    }

    @Override
    public void onAdPeriodEnded() {
      log("Ad Period Ended\n");
    }

    @Override
    public void seek(long timeMs) {
      // An ad was skipped. Skip to the content time.
      videoPlayer.seekTo(timeMs);
      log("seek");
    }

    @Override
    public VideoProgressUpdate getContentProgress() {
      return new VideoProgressUpdate(
          videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
    }
  };
}
SampleAdsWrapper.java

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 sola transmisión, debes estar listo para llamar a una transmisión de resguardo si la transmisión de DAI encuentra un error.

/** AdErrorListener implementation */
@Override
public void onAdError(AdErrorEvent event) {
  log(String.format("Error: %s\n", event.getError().getMessage()));
  // play fallback URL.
  log("Playing fallback Url\n");
  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 will be 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;
}
SampleAdsWrapper.java

Agrega código para el registro.

/** 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);
  }
}SampleAdsWrapper.java

Modifica MyActivity en videoplayerapp para crear una instancia de SampleAdsWrapper y llamar a esta. Además, llama a ImaSdkFactory.initialize() aquí con un método auxiliar para crear una instancia de ImaSdkSettings.

Importante: Para mejorar los tiempos de carga de IMA, llama al método ImaSdkFactory.initialize() lo antes posible en el ciclo de vida de la app. Si llamas al método con anticipación, se maximiza el tiempo que tiene IMA para cargar los recursos necesarios antes de la primera solicitud de transmisión. La llamada al método ImaSdkFactory.initialize() acepta una instancia de ImaSdkSettings. Asegúrate de usar los mismos valores de configuración aquí y cuando crees una instancia de AdsLoader. En este ejemplo, se usa el método auxiliar getImaSdkSettings() para garantizar que los valores de configuración sean los mismos. Para obtener más información, consulta la guía para optimizar el tiempo de carga de IMA>.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.res.Configuration;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.ImageButton;
import android.widget.ScrollView;
import android.widget.TextView;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;

/** Main Activity that plays media using {@link SampleVideoPlayer}. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String DEFAULT_STREAM_URL =
      "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
  private static final String APP_LOG_TAG = "ImaDaiExample";
  private static final String PLAYER_TYPE = "DAISamplePlayer";
  private static ImaSdkSettings imaSdkSettings;

  protected SampleVideoPlayer sampleVideoPlayer;
  protected ImageButton playButton;

  private boolean contentHasStarted = false;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);

    // Initialize the IMA SDK as early as possible when the app starts. If your app already
    // overrides Application.onCreate(), call this method inside the onCreate() method.
    // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
    ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

    View rootView = findViewById(R.id.videoLayout);
    sampleVideoPlayer =
        new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
    sampleVideoPlayer.enableControls(false);
    playButton = rootView.findViewById(R.id.playButton);
    final SampleAdsWrapper sampleAdsWrapper =
        new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
    sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);

    final ScrollView scrollView = findViewById(R.id.logScroll);
    final TextView textView = findViewById(R.id.logText);

    sampleAdsWrapper.setLogger(
        logMessage -> {
          Log.i(APP_LOG_TAG, logMessage);
          if (textView != null) {
            textView.append(logMessage);
          }
          if (scrollView != null) {
            scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
          }
        });

    // Set up play button listener to play video then hide play button.
    playButton.setOnClickListener(
        view -> {
          if (contentHasStarted) {
            sampleVideoPlayer.play();
          } else {
            contentHasStarted = true;
            sampleVideoPlayer.enableControls(true);
            sampleAdsWrapper.requestAndPlayAds();
          }
          playButton.setVisibility(View.GONE);
        });
    orientVideoDescription(getResources().getConfiguration().orientation);
  }
MyActivity.java

Agrega el método auxiliar getImaSdkSettings() para crear una instancia de ImaSdkSettings.

public static ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    imaSdkSettings.setPlayerType(PLAYER_TYPE);
    // Set any additional IMA SDK settings here.
  }
  return imaSdkSettings;
}MyActivity.java

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

<!-- 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>activity_my.xml

¡Felicitaciones! Ahora solicitas y muestras anuncios de video en tu app para Android. Para ajustar mejor 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.