Comienza a usar la extensión de IMA de Exoplayer

Los SDK de IMA facilitan la integración de anuncios multimedia en sus sitios web y aplicaciones. Los SDK de IMA pueden solicitar anuncios de cualquier servidor de anuncios compatible con VAST y administra la reproducción de anuncios en tus apps. Con los SDK de IMA del cliente, tú 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 un reproductor de video separado ubicado en la parte superior del reproductor de video de contenido de la app.

Esta guía muestra cómo integrar el SDK de IMA en un proyecto vacío de Android Studio usando el SDK Extensión de IMA de ExoPlayer. Si quieres ver una integración de muestra o continuar con ella, descarga la BasicExample de GitHub.

Descripción general de IMA del cliente

La implementación de IMA del lado del cliente implica cuatro componentes principales del SDK, como se demuestra en este guía:

  • AdDisplayContainer: Es un objeto contenedor en el que se renderizan los anuncios.
  • AdsLoader: Es un objeto que solicita anuncios y controla eventos de respuestas a solicitudes de anuncios. Solo debes crear una instancia de un cargador de anuncios, que puede reutilizarse durante el ciclo de vida de la aplicación.
  • AdsRequest: 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: Un objeto que contiene la respuesta a la solicitud de anuncios, controla la reproducción y escucha el anuncio eventos que activa el SDK.

Requisitos previos

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

1. Cómo crear un nuevo proyecto de Android Studio

Para crear tu proyecto de Android Studio, sigue estos 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 Configure your project, asigna un nombre al proyecto y selecciona Java para el 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 de la extensión al archivo sección de dependencias. Debido al tamaño de la extensión de IMA de ExoPlayer, implementa y habilita multidex. Esto es necesario para las apps que tienen la minSdkVersion configurada en 20 o un valor inferior. Además, agrega un compileOptions nuevo para especificar la información de compatibilidad de la versión de Java.

app/build.gradle 
android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
      minSdkVersion 21
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.1'

    ...
}

Agrega los permisos de usuario que requiere el SDK de IMA para solicitar anuncios.

app/src/main/AndroidManifest.xml 
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Cómo agregar declaraciones de intents

Si tu app está orientada a Android 11 (nivel de API 30) o versiones posteriores, las versiones actual y reciente del El SDK de IMA requiere una declaración de intención explícita para abrir vínculos web. Agrega el siguiente fragmento a en el archivo de manifiesto de tu app para habilitar los clics en el anuncio (los usuarios que hagan clic en el botón Más información ). 
  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

3. Cómo crear el contenedor de la IU del anuncio

Crea la vista que se usará como PlayerView de ExoPlayer mediante la creación de un elemento StyledPlayerView objeto con el ID adecuado. También cambia el De androidx.constraintlayout.widget.ConstraintLayout a LinearLayout.

app/src/main/res/layout/activity_main.xml 
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

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

</LinearLayout>

4. Agrega tu URL de contenido y la URL de etiqueta de anuncio para la solicitud de anuncios

Agrega entradas a strings.xml para almacenar tu URL de contenido y la URL de etiqueta de anuncio de VAST.

app/src/main/res/values/strings.xml 
<resources>
    <string name="app_name">Your_Project_Name</string>
    <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
    <string name="ad_tag_url"><![CDATA[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&impl=s&correlator=]]></string>

</resources>

5. Importa la extensión de IMA de ExoPlayer

Agrega las sentencias de importación para la extensión de ExoPlayer. Luego, actualiza el La clase MainActivity para extender Activity agregando variables privadas para PlayerView, SimpleExoPlayer y ImaAdsLoader.

app/src/main/java/com/example/project name/MainActivity.java 
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity</span> {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;</span>

}

6. Crea una instancia de adsLoader

Reemplaza el método onCreate y agrega las asignaciones de variables requeridas para crear un Nuevo objeto adsLoader con la URL de la etiqueta de anuncio.

app/src/main/java/com/example/project name/MainActivity.java 
...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

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

    playerView = findViewById(R.id.player_view);

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

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

7. Cómo inicializar y liberar el reproductor

Agrega métodos para inicializar y liberar el reproductor. Durante la inicialización método, crea la SimpleExoPlayer. Luego, crea el AdsMediaSource. y configúrala en el reproductor.

app/src/main/java/com/example/project name/MainActivity.java 
public class MainActivity extends Activity {

  ...

  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(getString(R.string.content_url));
    Uri adTagUri = Uri.parse(getString(R.string.ad_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);
  }
}

8. Controla los eventos del jugador

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

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
app/src/main/java/com/example/project name/MainActivity.java 
public class MainActivity extends Activity {

  private PlayerView playerView;
  private SimpleExoPlayer player;
  private ImaAdsLoader adsLoader;

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

      playerView = findViewById(R.id.player_view);

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

  @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
  protected void onDestroy() {
    super.onDestroy();
    adsLoader.release();
  }

  ...

}

Eso es todo. Ahora está solicitando y mostrando anuncios con el SDK de IMA. Para obtener más información SDK, consulta las otras guías o la muestras en GitHub.