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 veiculaçã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 lida com a reprodução de anúncios. Os anúncios são veiculados em um player de vídeo separado posicionado sobre o 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 ExoPlayer IMA. Se você quiser conferir ou seguir uma integração de exemplo completa, faça o download do BasicExample no GitHub.

Observação:para informações sobre a integração com outras plataformas ou o uso dos SDKs DAI do IMA, consulte SDKs do Interactive Media Ads.

Visão geral do IMA do lado do cliente

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

• AdDisplayContainer: um objeto de contêiner que especifica onde a IMA renderiza elementos da interface do anúncio e mede a visibilidade, incluindo Active View e Open Measurement.
• 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úncios. As solicitações de anúncios especificam o URL da tag de anúncio VAST, além de outros parâmetros, como as 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 ouve eventos de anúncios acionados pelo SDK.

Observação:como a extensão do IMA do ExoPlayer envolve o SDK do IMA neste guia, AdsRequest e AdsManager estão sendo usados, mas não são chamados explicitamente.

Pré-requisitos

Antes de começar, você precisa do Android Studio 3.0 ou 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 Choose your project, selecione o modelo Empty Activity.
4. Clique em Próxima.
5. Na página Configurar seu projeto, nomeie o projeto e selecione Java como linguagem.
   Observação:o SDK do IMA é compatível com o Kotlin. No entanto, o exemplo abordado neste guia usa Java.
6. Clique em Concluir.

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

Primeiro, no arquivo build.gradle 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.

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'

    ...
}

Adicione as permissões do usuário necessárias para solicitar anúncios ao SDK do IMA.

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>

Adicionar declarações de intent

Se o app for destinado ao Android 11 (nível 30 da API) ou versões mais recentes, as versões atuais e recentes do SDK do IMA vão exigir uma declaração explícita de intenção para abrir links da Web. Adicione o snippet a seguir ao arquivo de manifesto do app para ativar os cliques no anúncio (os usuários clicam no botão Saiba mais).

Observação:as versões futuras do SDK do IMA vão incluir essas declarações automaticamente e serão mescladas com o arquivo de manifesto do seu aplicativo.

  <?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. Criar o contêiner da interface do anúncio

Crie a visualização a ser usada como a PlayerView do ExoPlayer criando um objeto StyledPlayerView com um ID adequado. Mude também o androidx.constraintlayout.widget.ConstraintLayout para um 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. Adicionar o URL do conteúdo e o URL da tag do anúncio para a solicitação de anúncios

Adicione entradas a strings.xml para armazenar o URL do conteúdo e o URL da tag de anúncio 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. Importar a extensão IMA do ExoPlayer

Adicione as instruções de importação para a extensão do ExoPlayer. Em seguida, atualize a classe MainActivity para estender Activity adicionando variáveis particulares para PlayerView, SimpleExoPlayer e 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 {

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

}

6. Criar uma instância adsLoader

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

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. Inicializar e liberar o player

Adicione métodos para inicializar e liberar o player. No método de inicialização, crie o SimpleExoPlayer. Em seguida, crie o AdsMediaSource e defina-o para o jogador.

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

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

• onStart
• onResume
• onStop
• onPause
• onDestroy

Observação:o código de exemplo usa onStart/onStop para as versões 24 e mais recentes do SDK do Android e onResume/onPause para versões anteriores à 24.

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

  ...

}

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