Comienza a usar la extensión de IMA de Exoplayer

Los SDKs de IMA facilitan la integración de anuncios multimedia en tus sitios web y aplicaciones. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administrar la reproducción de anuncios en tus aplicaciones. Con los SDKs del cliente de IMA, mantienes el control de la reproducción de videos de contenido, mientras que el SDK controla la reproducción de anuncios. Los anuncios se reproducen en un reproductor de video independiente ubicado en la parte superior del reproductor de video de contenido de la app.

En esta guía, se muestra cómo integrar el SDK de IMA en un proyecto vacío de Android Studio con la extensión de IMA de ExoPlayer. Si quieres ver o seguir una integración de muestra completa, descarga BasicExample desde GitHub.

Descripción general del IMA del cliente

La implementación del SDK del cliente de IMA implica cuatro componentes principales del SDK, que se demuestran en esta guía:

  • AdDisplayContainer: Es un objeto contenedor que especifica dónde IMA renderiza los elementos de la IU de los anuncios y mide la visibilidad, incluidos Vista activa y Open Measurement.
  • AdsLoader: Es un objeto que solicita anuncios y controla eventos de las respuestas a las solicitudes de anuncios. Solo debes crear una instancia del 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: 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

Antes de comenzar, necesitas Android Studio 3.0 o una versión posterior.

1. Crea un proyecto nuevo de Android Studio

Para crear tu proyecto de Android Studio, completa los siguientes pasos:

  1. Inicia Android Studio.
  2. Selecciona Start a new Android Studio project.
  3. En la página Elige tu proyecto, selecciona la plantilla Actividad vacía.
  4. Haz clic en Siguiente.
  5. En la página Configura tu proyecto, asígnale un nombre y selecciona Java como lenguaje.
  6. Haz clic en Finalizar.

2. Agrega la extensión de IMA de ExoPlayer a tu proyecto

Primero, en el archivo build.gradle a nivel de la aplicación, agrega importaciones para la extensión a la sección de dependencias. Debido al tamaño de la extensión de IMA de ExoPlayer, implementa y habilita multidex aquí. Esto es necesario para las apps con minSdkVersion establecido en 20 o un valor inferior. Además, agrega un nuevo compileOptions para especificar la información de compatibilidad de la versión de Java. 

apply plugin: 'com.android.application'

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdk 36

    // Java 17 required by Gradle 8+
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    defaultConfig {
        applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
        minSdkVersion 21
        targetSdkVersion 36
        multiDexEnabled true
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.8.0"
    implementation "androidx.media3:media3-ui:$media3_version"
    implementation "androidx.media3:media3-exoplayer:$media3_version"

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

    implementation 'androidx.multidex:multidex:2.0.1'
}

build.gradle

3. Crea el contenedor de la IU del anuncio

Crea la vista para usarla como PlayerView de ExoPlayer creando un androidx.media3.ui.PlayerView. Además, cambia el elemento androidx.constraintlayout.widget.ConstraintLayout por un elemento LinearLayout. 

<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: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

4. Importa la extensión de IMA de ExoPlayer

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

import static android.os.Build.VERSION.SDK_INT;

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.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;

MyActivity.java

Luego, actualiza la clase MainActivity para que extienda Activity agregando variables privadas para PlayerView, ExoPlayer, ImaAdsLoader y ImaSdkSettings: 

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

  private static final String SAMPLE_VIDEO_URL =
      "https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
  private static final String SAMPLE_VAST_TAG_URL =
      "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
          + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90"
          + "&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator=";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;
  private ImaSdkSettings imaSdkSettings;

MyActivity.java

5. Crea una instancia de adsLoader

Anula el método onCreate y agrega las asignaciones de variables necesarias para crear un objeto adsLoader nuevo con la URL de la etiqueta del anuncio. 

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

  // 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);

  // Create an AdsLoader.
  adsLoader =
      new ImaAdsLoader.Builder(/* context= */ this)
          .setAdEventListener(buildAdEventListener())
          .setImaSdkSettings(getImaSdkSettings())
          .build();
}

MyActivity.java

Crea el método buildAdEventListener() para devolver un objeto AdEventListener y registrar eventos de IMA para la depuración. La extensión de IMA de ExoPlayer ya controla los eventos de IMA y no necesita nada adicional aquí para funcionar. 

public AdEvent.AdEventListener buildAdEventListener() {
  logText = findViewById(R.id.logText);
  logText.setMovementMethod(new ScrollingMovementMethod());

  return event -> {
    AdEvent.AdEventType eventType = event.getType();
    if (eventType == AdEvent.AdEventType.AD_PROGRESS) {
      return;
    }
    String log = "IMA event: " + eventType;
    if (logText != null) {
      logText.append(log + "\n");
    }
    Log.i(LOG_TAG, log);
  };
}

MyActivity.java

Crea el método auxiliar getImaSdkSettings() para devolver un objeto ImaSdkSettings y establecer cualquier parámetro de configuración del SDK de IMA: 

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

6. Inicializa y libera el reproductor

Agrega métodos para liberar e inicializar el reproductor. En el método initializePlayer(), crea el ExoPlayer. Luego, crea el AdsMediaSource y configúralo en el reproductor:

private void releasePlayer() {
  adsLoader.setPlayer(null);
  playerView.setPlayer(null);
  player.release();
  player = null;
}

private void initializePlayer() {
  // Set up the factory for media sources, passing the ads loader and ad view providers.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  MediaSource.Factory mediaSourceFactory =
      new DefaultMediaSourceFactory(dataSourceFactory)
          .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);

  // Create an ExoPlayer 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 content URI and ad tag URI.
  Uri contentUri = Uri.parse(SAMPLE_VIDEO_URL);
  Uri adTagUri = Uri.parse(SAMPLE_VAST_TAG_URL);
  MediaItem mediaItem =
      new MediaItem.Builder()
          .setUri(contentUri)
          .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
          .build();

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

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

MyActivity.java

7. Cómo controlar eventos del reproductor

Por último, crea devoluciones de llamada para los eventos del ciclo de vida del reproductor:

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

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

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

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

@Override
protected void onDestroy() {
  adsLoader.release();

  super.onDestroy();
}

MyActivity.java

Ahora solicitas y muestras anuncios correctamente con el SDK de IMA. Para obtener información sobre funciones más avanzadas, consulta las otras guías o los ejemplos en GitHub.