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 para Android. En esta guía, se muestra cómo usar la extensión de IMA de ExoPlayer. Esta extensión usa el SDK de IMA DAI para solicitar y reproducir transmisiones de medios con anuncios y contenido.

A continuación, se enumeran los beneficios de la extensión:

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

La extensión de IMA de ExoPlayer admite los protocolos de transmisión HLS y DASH. A continuación, se incluye un resumen:

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

La versión 1.1.0 y las versiones posteriores de ExoPlayer-IMA 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 ver 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 la DAI

Crea 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 Elige tu proyecto, selecciona la plantilla No Activity.
Haz clic en Siguiente.
En la página Configura tu proyecto, asígnale un nombre 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 de IMA de ExoPlayer a tu proyecto

Para agregar la extensión de 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.8.0"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.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 del usuario que necesita el SDK de DAI de IMA 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 tus parámetros de transmisión

Consulta la página de muestra de transmisiones de IMA para ver recursos de muestra de transmisiones 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 de 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 de 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 de Big Buck Bunny (en vivo), agrega su clave de activo. Puedes encontrar más transmisiones para probar en la página de transmisiones de muestra de la IMA.

Crea una constante KEY_ADS_LOADER_STATE para guardar y recuperar el estado de 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 ella, busca PlayerView y verifica si hay un AdsLoader.State guardado. 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 método ImaSdkFactory.initialize() lo antes posible en el ciclo de vida de la app. Llamar al método con anticipación maximiza el tiempo que IMA tiene 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>.

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 objeto MediaItem con la clave del activo 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 al jugador

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

Establece las referencias del reproductor en nulas 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

Cómo controlar eventos del reproductor

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

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

Para los niveles de API de Android anteriores al 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 evento onSaveInstanceState() 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 las pruebas, usa estos parámetros de transmisión:
- ID de CMS: "2548831"
- ID de video: "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 la operación se realiza correctamente, puedes solicitar y reproducir una transmisión de medios con la extensión de IMA de ExoPlayer. Para ver el ejemplo completo, consulta Ejemplos de DAI para Android en GitHub.