Primeiros passos com a extensão IMA do Exoplayer

Os SDKs do IMA facilitam a integração de anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a reprodução de anúncios nos seus apps. Com os SDKs do lado do cliente do IMA, você mantém o controle da reprodução de vídeo de conteúdo, enquanto o SDK processa a reprodução de anúncios. Os anúncios são veiculados em um player de vídeo separado, posicionado acima do player de vídeo de conteúdo do app.

Este guia demonstra como integrar o SDK do IMA a um projeto vazio do Android Studio usando a extensão do IMA do ExoPlayer. Se você quiser ver ou acompanhar uma amostra de integração concluída, faça o download do BasicExample no GitHub.

Visão geral do lado do cliente da IMA

A implementação do IMA do lado do cliente envolve quatro componentes principais do SDK, que são demonstrados neste guia:

  • AdDisplayContainer: um objeto contêiner que especifica onde a IMA renderiza elementos da interface do anúncio e mede a visibilidade, incluindo o Active View e a Medição aberta.
  • AdsLoader: um objeto que solicita anúncios e processa eventos de respostas de solicitação de anúncios. Você só precisa instanciar um carregador de anúncios, que pode ser reutilizado durante toda a vida útil do aplicativo.
  • AdsRequest: um objeto que define uma solicitação de anúncio. As solicitações de anúncios especificam o URL da tag de anúncio VAST, além de outros parâmetros, como dimensões do anúncio.
  • AdsManager: um objeto que contém a resposta à solicitação de anúncios, controla a reprodução de anúncios e detecta eventos de anúncio acionados pelo SDK.

Pré-requisitos

Antes de começar, você precisa do Android Studio 3.0 ou uma versão mais recente.

1. Criar um novo projeto do Android Studio

Para criar seu projeto do Android Studio, siga estas etapas:

  1. Inicie o Android Studio.
  2. Selecione Start a new Android Studio project.
  3. Na página Escolher seu projeto, selecione o modelo Atividade vazia.
  4. Clique em Próxima.
  5. Na página Configurar seu projeto, nomeie o projeto e selecione Java como linguagem.
  6. Clique em Concluir.

2. Adicionar a extensão IMA do ExoPlayer ao projeto

Primeiro, no arquivo build.gradle no nível do aplicativo, adicione importações para a extensão à seção de dependências. Devido ao tamanho da extensão IMA do ExoPlayer, implemente e ative o multidex aqui. Isso é necessário para apps com minSdkVersion definido como 20 ou menos. Além disso, adicione um novo compileOptions para especificar as informações de compatibilidade da versão do 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. Criar o contêiner da interface do anúncio

Crie a visualização para usar como o ExoPlayer PlayerView criando um androidx.media3.ui.PlayerView. Além disso, mude o androidx.constraintlayout.widget.ConstraintLayout para um 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. Importar a extensão IMA do ExoPlayer

Adicione as instruções de importação para a extensão do 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

Em seguida, atualize a classe MainActivity para estender Activity adicionando variáveis privadas para PlayerView, ExoPlayer, ImaAdsLoader e 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. Criar uma instância adsLoader

Substitua o método onCreate e adicione as atribuições de variáveis necessárias para criar um novo objeto adsLoader com o URL da tag de anúncio. 

@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

Crie o método buildAdEventListener() para retornar um objeto AdEventListener e registrar eventos da IMA para depuração. A extensão do ExoPlayer IMA já processa eventos do IMA e não precisa de mais nada 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

Crie o método auxiliar getImaSdkSettings() para retornar um objeto ImaSdkSettings e definir as configurações do SDK do IMA: 

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

6. Inicializar e liberar o player

Adicione métodos para liberar e inicializar o player. No método initializePlayer(), crie o ExoPlayer. Em seguida, crie o AdsMediaSource e defina-o para o player:

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. Processar eventos do player

Por fim, crie callbacks para os eventos do ciclo de vida do player:

  • 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

Agora você está solicitando e mostrando anúncios com o SDK do IMA. Para saber mais sobre recursos avançados, consulte os outros guias ou os exemplos no GitHub.