Para analizar nuestros productos y proporcionar comentarios sobre ellos, únete al canal oficial de Ad Manager en Discord, en el servidor Google Advertising and Measurement Community.

Comienza a usar la extensión de IMA de ExoPlayer

ExoPlayer es un reproductor multimedia de Android. En esta guía, se muestra cómo usar la extensión IMA de ExoPlayer. Esta extensión usa el SDK de IMA DAI para solicitar y reproducir transmisiones de contenido multimedia con anuncios y contenido.

En la siguiente lista, se incluyen los beneficios de la extensión:

Simplifica el código necesario para integrar las funciones de IMA.
Reduce el tiempo necesario para actualizar a las versiones nuevas de IMA.

La extensión IMA de ExoPlayer admite los protocolos de transmisión HLS y DASH. Aquí tienes un resumen:

Compatibilidad con la transmisión de la extensión ExoPlayer-IMA
	Transmisión en vivo	Transmisiones de VOD
HLS
DASH

ExoPlayer-IMA versión 1.1.0 y versiones posteriores admiten transmisiones en vivo de DASH.

En esta guía, se usa la guía de ExoPlayer para ayudarte a crear una app completa y a integrar la extensión. Para obtener una app de ejemplo completa, consulta ExoPlayerExample en GitHub.

Requisitos previos

Android Studio
AndroidX Media3 ExoPlayer versión 1.0.0 o posterior para la compatibilidad con DAI

Cómo crear un proyecto nuevo de Android Studio

Para crear tu proyecto de Android Studio, sigue estos pasos:

Inicia Android Studio.
Selecciona Start a new Android Studio project.
En la página Choose your project, selecciona la plantilla No Activity.
Haz clic en Siguiente.
En la página Configure your project, asigna un nombre a tu proyecto y selecciona Java como el lenguaje. Nota: El SDK de IMA DAI funciona con Kotlin, pero en esta guía se usan ejemplos de Java.

Haz clic en Finalizar.

Agrega la extensión IMA de ExoPlayer a tu proyecto

Para agregar la extensión IMA de ExoPlayer, haz lo siguiente:

Incluye las siguientes importaciones en la sección dependencies del archivo build.gradle de tu app:

dependencies {
    def media3_version = "1.9.1"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.0"))
    implementation("androidx.appcompat:appcompat:1.7.1")
    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")

    // The library adds the IMA ExoPlayer integration for ads.
    implementation("androidx.media3:media3-exoplayer-ima:$media3_version")
}build.gradle

Agrega los permisos de usuario que necesita el SDK de IMA DAI para solicitar anuncios:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>AndroidManifest.xml

Configura la IU de ExoPlayer

Para configurar la IU de ExoPlayer, haz lo siguiente:

Crea el objeto PlayerView para ExoPlayer.

Cambia la vista androidx.constraintlayout.widget.ConstraintLayout a una vista LinearLayout, como lo recomienda la extensión IMA de ExoPlayer:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:fitsSystemWindows="true"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <!-- UI element for viewing SDK event log -->
    <TextView
        android:id="@+id/logText"
        android:gravity="bottom"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:maxLines="100"
        android:scrollbars="vertical"
        android:textSize="@dimen/font_size">
    </TextView>

</LinearLayout>
activity_my.xml

Agrega los parámetros de transmisión

Consulta la página de transmisión de muestra de IMA para obtener recursos de transmisión de muestra y probar tu proyecto. Para configurar tus propias transmisiones, consulta la sección de Ad Manager sobre DAI.

En este paso, se configura una transmisión en vivo. La extensión IMA de ExoPlayer también admite transmisiones de VOD de DAI. Para saber qué cambios necesita tu app para las transmisiones de VOD, consulta el paso para las transmisiones de video on demand (VOD).

Importa la extensión IMA de ExoPlayer

Agrega las siguientes instrucciones de importación para la extensión de ExoPlayer:

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import android.text.method.ScrollingMovementMethod;
import android.util.Log;
import android.widget.TextView;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.ui.PlayerView;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import java.util.HashMap;
import java.util.Map;
MyActivity.java

En MyActivity.java, agrega estas variables privadas:
Para realizar pruebas con la transmisión HLS Big Buck Bunny (Live), agrega su clave de elemento. Puedes encontrar más transmisiones para probar en la página de transmisión de muestra de IMA.

Crea una constante KEY_ADS_LOADER_STATE para guardar y recuperar el estado AdsLoader:

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
  private ImaSdkSettings imaSdkSettings;
MyActivity.java

Crea una instancia de `adsLoader`

Anula el método onCreate. En él, busca el PlayerView y verifica si hay un guardado AdsLoader.State. Puedes usar este estado cuando inicialices el objeto adsLoader.

@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());

  playerView = findViewById(R.id.player_view);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

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

Importante: Para mejorar los tiempos de carga de IMA, llama al ImaSdkFactory.initialize() método lo antes posible en el ciclo de vida de la app. Llamar al método con anticipación maximiza el tiempo para que IMA cargue 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 Optimiza el tiempo de carga de IMA>.

Agrega métodos para inicializar el reproductor

Agrega un método para inicializar el reproductor. Este método debe hacer lo siguiente:

Crea una instancia de AdsLoader.
Crea el ExoPlayer.
Crea un MediaItem con la clave de elemento de la transmisión en vivo.
Establece el MediaItem para tu reproductor.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer and set it as the player for content and ads.
  player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
  playerView.setPlayer(player);
  adsLoader.setPlayer(player);

  // Create the MediaItem to play, specifying the stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

Agrega un método para liberar el reproductor

Agrega un método para liberar el reproductor. Este método debe realizar las siguientes acciones en secuencia:

Establece las referencias del reproductor en nulo y libera los recursos del reproductor.
Libera el estado adsLoader.

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

Controla los eventos del reproductor

Para controlar los eventos del reproductor, crea devoluciones de llamada para los eventos del ciclo de vida de la actividad para administrar la reproducción de la transmisión.

En el caso del nivel de API 24 de Android y versiones posteriores, usa los siguientes métodos:

En el caso de los niveles de API de Android anteriores a 24, usa los siguientes métodos:

Los métodos onStart() y onResume() se asignan a playerView.onResume(), mientras que onStop() y onPause() se asignan a playerView.onPause().

En este paso, también se usa el onSaveInstanceState() evento para guardar el adsLoaderState.

@Override
public void onStart() {
  super.onStart();
  if (Util.SDK_INT > 23) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onResume() {
  super.onResume();
  if (Util.SDK_INT <= 23 || player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
  if (Util.SDK_INT <= 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onStop() {
  super.onStop();
  if (Util.SDK_INT > 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

Configuración de la transmisión de VOD (opcional)

Si tu app necesita reproducir contenido de VOD con anuncios, sigue estos pasos:

Agrega un CMS ID y un Video ID para una transmisión de VOD. Para realizar pruebas, usa estos parámetros de transmisión:
- CMS ID: "2548831"
- Video ID: "tears-of-steel"

Crea un URI de VOD de SSAI con el método ImaServerSideAdInsertionUriBuilder():

/**
 * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
 *
 * @param cmsId The CMS ID of the VOD stream.
 * @param videoId The video ID of the VOD stream.
 * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the VOD stream.
 */
public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setContentSourceId(cmsId)
      .setVideoId(videoId)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

Establece el nuevo URI de transmisión de VOD como el elemento multimedia de tu reproductor con el método MediaItem.fromUri().

Si se realiza correctamente, puedes solicitar y reproducir una transmisión de contenido multimedia con la extensión IMA de ExoPlayer. Para obtener el ejemplo completo, consulta las muestras de DAI de Android en GitHub.