Com os SDKs do IMA, é fácil integrar anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer de anúncios compatíveis com VAST e gerencie a reprodução de anúncios nos seus apps. Com os SDKs do IMA do cliente, você mantém o controle da reprodução do conteúdo de vídeo, enquanto o SDK processa a reprodução de anúncios. Os anúncios são reproduzidos em um um player de vídeo separado posicionado na parte superior do player de vídeo do app.
Este guia demonstra como integrar o SDK do IMA a um projeto vazio do Android Studio usando o a VideoView do Android para mostrar conteúdo e anúncios. Para acompanhar um exemplo completo faça o download do BasicExample do GitHub.
.Visão geral do cliente do IMA
A implementação do IMA no lado do cliente envolve quatro componentes principais do SDK, que são demonstrados neste guia:
AdDisplayContainer: Um objeto contêiner onde os anúncios são renderizados.AdsLoader: Um objeto que solicita anúncios e manipula os eventos das respostas de solicitações de anúncios. Você só deve instanciar um carregador de anúncios, que pode ser reutilizado durante 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, bem como parâmetros adicionais, como dimensões de anúncio.AdsManager: Objeto que contém a resposta à solicitação de anúncios, controla a reprodução e detecta o anúncio. de eventos acionados pelo SDK.
Pré-requisitos
1. Criar um novo projeto do Android Studio
Para criar o projeto do Android Studio, siga estas etapas:
- Inicie o Android Studio.
- Selecione Iniciar um novo projeto do Android Studio.
- Na página Choose your project, selecione o modelo Empty Activity.
- Clique em Próxima.
- Na página Configure your project, dê um nome ao projeto e selecione Java como a linguagem.
- Clique em Finish.
2. Adicionar o SDK do IMA ao seu projeto
Primeiro, no arquivo build.gradle do nível do aplicativo, adicione importações para o SDK do IMA ao
na seção de dependências. Devido ao tamanho do SDK do IMA, implemente e ative o multidex aqui. Isso
é necessário para apps com a minSdkVersion definida como 20 ou menor. Além disso, adicione novos
compileOptions para especificar as informações de compatibilidade da versão do Java.
android {
namespace 'com.google.ads.interactivemedia.v3.samples.videoplayerapp'
compileSdkVersion 34
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
defaultConfig {
applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
minSdkVersion 21
targetSdkVersion 34
multiDexEnabled true
versionCode 1
versionName "1.0"
}
...
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.browser:browser:1.6.0'
implementation 'androidx.media:media:1.6.0'
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.35.1'
...
}
3. Adicionar as permissões necessárias do SDK do IMA
Adicione as permissões de usuário exigidas pelo SDK do IMA para solicitar anúncios.
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>
4. Atualizar o layout do app
Atualize o layout do app para incluir um VideoView para abrir o conteúdo e
anúncios.
<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">
<RelativeLayout
android:layout_width="match_parent"
android:layout_height="0dp"
android:layout_weight="0.4"
android:orientation="vertical"
android:id="@+id/videoPlayerContainer" >
<VideoView
android:id="@+id/videoView"
android:layout_width="match_parent"
android:layout_height="match_parent" />
<ImageButton
android:id="@+id/playButton"
android:contentDescription="@string/play_description"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:src="@drawable/ic_action_play_over_video"
android:background="@null" />
</RelativeLayout>
<FrameLayout
android:layout_width="match_parent"
android:layout_height="0dp"
android:layout_weight="0.6"
android:id="@+id/videoDescription" >
<TextView
android:id="@+id/playerDescription"
android:text="@string/app_name"
android:textAlignment="center"
android:gravity="center_horizontal"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:textSize="@dimen/font_size" />
</FrameLayout>
</LinearLayout>
5. Importar o IMA para a atividade principal
Adicione as instruções de importação do SDK do IMA. Depois, atualize o
MyActivity para estender AppCompatActivity. A
A classe AppCompatActivity permite o suporte de recursos de plataforma mais recentes em
Dispositivos Android. Em seguida, adicione um conjunto de variáveis privadas que serão usadas no app.
import android.content.Context;
import android.media.AudioManager;
import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;
import android.view.View;
import android.view.ViewGroup;
import android.widget.MediaController;
import android.widget.VideoView;
import com.google.ads.interactivemedia.v3.api.AdDisplayContainer;
import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsManager;
import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
import com.google.ads.interactivemedia.v3.api.AdsRenderingSettings;
import com.google.ads.interactivemedia.v3.api.AdsRequest;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import java.util.Arrays;
...
public class MyActivity extends AppCompatActivity {
private static final String LOGTAG = "IMABasicSample";
private static final String SAMPLE_VIDEO_URL =
"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
/**
* IMA sample tag for a single skippable inline video ad. See more IMA sample tags at
* https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
*/
private static final String SAMPLE_VAST_TAG_URL =
"https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
+ "single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast"
+ "&unviewed_position_start=1&env=vp&impl=s&correlator=";
// Factory class for creating SDK objects.
private ImaSdkFactory sdkFactory;
// The AdsLoader instance exposes the requestAds method.
private AdsLoader adsLoader;
// AdsManager exposes methods to control ad playback and listen to ad events.
private AdsManager adsManager;
// The saved content position, used to resumed content following an ad break.
private int savedPosition = 0;
// This sample uses a VideoView for content and ad playback. For production
// apps, Android's Exoplayer offers a more fully featured player compared to
// the VideoView.
private VideoView videoPlayer;
private MediaController mediaController;
private View playButton;
private VideoAdPlayerAdapter videoAdPlayerAdapter;
}
6. Criar a classe VideoAdPlayerAdapter
Crie uma classe VideoAdPlayerAdapter com o VideoView.
e adaptá-lo ao sistema
VideoAdPlayer
. Esta classe manipulará o conteúdo e a reprodução de anúncios e conterá o conjunto de
métodos que um player de vídeo precisa implementar para ser usado pelo SDK do IMA.
import android.media.AudioManager;
import android.media.MediaPlayer;
import android.net.Uri;
import android.util.Log;
import android.widget.VideoView;
import com.google.ads.interactivemedia.v3.api.AdPodInfo;
import com.google.ads.interactivemedia.v3.api.player.AdMediaInfo;
import com.google.ads.interactivemedia.v3.api.player.VideoAdPlayer;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import java.util.ArrayList;
import java.util.List;
import java.util.Timer;
import java.util.TimerTask;
/** Example implementation of IMA's VideoAdPlayer interface. */
public class VideoAdPlayerAdapter implements VideoAdPlayer {
private static final String LOGTAG = "IMABasicSample";
private static final long POLLING_TIME_MS = 250;
private static final long INITIAL_DELAY_MS = 250;
private final VideoView videoPlayer;
private final AudioManager audioManager;
private final List<VideoAdPlayerCallback> videoAdPlayerCallbacks = new ArrayList<>();
private Timer timer;
private int adDuration;
// The saved ad position, used to resumed ad playback following an ad click-through.
private int savedAdPosition;
private AdMediaInfo loadedAdMediaInfo;
public VideoAdPlayerAdapter(VideoView videoPlayer, AudioManager audioManager) {
this.videoPlayer = videoPlayer;
this.videoPlayer.setOnCompletionListener(
(MediaPlayer mediaPlayer) -> notifyImaOnContentCompleted());
this.audioManager = audioManager;
}
}
7. Substituir os métodos VideoAdPlayer
Substitua os seguintes métodos VideoAdPlayer:
O método playAd() define o URL do conteúdo ou do anúncio e define um listener para começar.
a reprodução após o carregamento da mídia.
/** Example implementation of IMA's VideoAdPlayer interface. */
public class VideoAdPlayerAdapter implements VideoAdPlayer {
...
@Override
public void addCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
videoAdPlayerCallbacks.add(videoAdPlayerCallback);
}
@Override
public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) {
// This simple ad loading logic works because preloading is disabled. To support
// preloading ads your app must maintain state for the currently playing ad
// while handling upcoming ad downloading and buffering at the same time.
// See the IMA Android preloading guide for more info:
// https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/preload
loadedAdMediaInfo = adMediaInfo;
}
@Override
public void pauseAd(AdMediaInfo adMediaInfo) {
Log.i(LOGTAG, "pauseAd");
savedAdPosition = videoPlayer.getCurrentPosition();
stopAdTracking();
}
@Override
public void playAd(AdMediaInfo adMediaInfo) {
videoPlayer.setVideoURI(Uri.parse(adMediaInfo.getUrl()));
videoPlayer.setOnPreparedListener(
mediaPlayer -> {
adDuration = mediaPlayer.getDuration();
if (savedAdPosition > 0) {
mediaPlayer.seekTo(savedAdPosition);
}
mediaPlayer.start();
startAdTracking();
});
videoPlayer.setOnErrorListener(
(mediaPlayer, errorType, extra) -> notifyImaSdkAboutAdError(errorType));
videoPlayer.setOnCompletionListener(
mediaPlayer -> {
savedAdPosition = 0;
notifyImaSdkAboutAdEnded();
});
}
@Override
public void release() {
// any clean up that needs to be done.
}
@Override
public void removeCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
videoAdPlayerCallbacks.remove(videoAdPlayerCallback);
}
@Override
public void stopAd(AdMediaInfo adMediaInfo) {
Log.i(LOGTAG, "stopAd");
stopAdTracking();
}
/** Returns current volume as a percent of max volume. */
@Override
public int getVolume() {
return audioManager.getStreamVolume(AudioManager.STREAM_MUSIC)
/ audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC);
}
8. Configurar o acompanhamento de anúncios
Para registrar eventos de anúncios,
VideoAdPlayerCallback.onAdProgress precisa ser chamado à medida que o conteúdo e os anúncios avançam. Para isso, configure um timer para chamar onAdProgress() em um intervalo definido.
/** Example implementation of IMA's VideoAdPlayer interface. */
public class VideoAdPlayerAdapter implements VideoAdPlayer {
...
private void startAdTracking() {
Log.i(LOGTAG, "startAdTracking");
if (timer != null) {
return;
}
timer = new Timer();
TimerTask updateTimerTask =
new TimerTask() {
@Override
public void run() {
VideoProgressUpdate progressUpdate = getAdProgress();
notifyImaSdkAboutAdProgress(progressUpdate);
}
};
timer.schedule(updateTimerTask, POLLING_TIME_MS, INITIAL_DELAY_MS);
}
private void notifyImaSdkAboutAdEnded() {
Log.i(LOGTAG, "notifyImaSdkAboutAdEnded");
savedAdPosition = 0;
for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) {
callback.onEnded(loadedAdMediaInfo);
}
}
private void notifyImaSdkAboutAdProgress(VideoProgressUpdate adProgress) {
for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) {
callback.onAdProgress(loadedAdMediaInfo, adProgress);
}
}
/**
* @param errorType Media player's error type as defined at
* https://cs.android.com/android/platform/superproject/+/master:frameworks/base/media/java/android/media/MediaPlayer.java;l=4335
* @return True to stop the current ad playback.
*/
private boolean notifyImaSdkAboutAdError(int errorType) {
Log.i(LOGTAG, "notifyImaSdkAboutAdError");
switch (errorType) {
case MediaPlayer.MEDIA_ERROR_UNSUPPORTED:
Log.e(LOGTAG, "notifyImaSdkAboutAdError: MEDIA_ERROR_UNSUPPORTED");
break;
case MediaPlayer.MEDIA_ERROR_TIMED_OUT:
Log.e(LOGTAG, "notifyImaSdkAboutAdError: MEDIA_ERROR_TIMED_OUT");
break;
default:
break;
}
for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) {
callback.onError(loadedAdMediaInfo);
}
return true;
}
public void notifyImaOnContentCompleted() {
Log.i(LOGTAG, "notifyImaOnContentCompleted");
for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) {
callback.onContentComplete();
}
}
private void stopAdTracking() {
Log.i(LOGTAG, "stopAdTracking");
if (timer != null) {
timer.cancel();
timer = null;
}
}
@Override
public VideoProgressUpdate getAdProgress() {
long adPosition = videoPlayer.getCurrentPosition();
return new VideoProgressUpdate(adPosition, adDuration);
}
}
9. Iniciar o IMA no método onCreate
Substitua o método onCreate e adicione as atribuições de variáveis necessárias para iniciar
IMA. Nesta etapa, crie o seguinte:
ImaSdkSettingsAdsLoader
Esta etapa também cria um VideoAdPlayerAdapter, uma classe que você criará depois.
neste guia.
Por fim, configure o botão de reprodução para solicitar anúncios e os oculte quando clicado.
app/src/main/java/com/example/project name/MyActivity.java
...
public class MyActivity extends AppCompatActivity {
...
private VideoView videoPlayer;
private MediaController mediaController;
private View playButton;
private VideoAdPlayerAdapter videoAdPlayerAdapter;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
// Create the UI for controlling the video view.
mediaController = new MediaController(this);
videoPlayer = findViewById(R.id.videoView);
mediaController.setAnchorView(videoPlayer);
videoPlayer.setMediaController(mediaController);
// Create an ad display container that uses a ViewGroup to listen to taps.
ViewGroup videoPlayerContainer = findViewById(R.id.videoPlayerContainer);
AudioManager audioManager = (AudioManager) getSystemService(Context.AUDIO_SERVICE);
videoAdPlayerAdapter = new VideoAdPlayerAdapter(videoPlayer, audioManager);
sdkFactory = ImaSdkFactory.getInstance();
AdDisplayContainer adDisplayContainer =
ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter);
// Create an AdsLoader.
ImaSdkSettings settings = sdkFactory.createImaSdkSettings();
adsLoader = sdkFactory.createAdsLoader(this, settings, adDisplayContainer);
// When the play button is clicked, request ads and hide the button.
playButton = findViewById(R.id.playButton);
playButton.setOnClickListener(
view -> {
videoPlayer.setVideoPath(SAMPLE_VIDEO_URL);
requestAds(SAMPLE_VAST_TAG_URL);
view.setVisibility(View.GONE);
});
}
}
10. Adicionar listeners do AdsLoader
Adicione listeners para addAdErrorListener e
addAdsLoadedListener No AdsLoadedListener, crie o
AdsManager e configure o listener de erro AdsManager.
@Override
protected void onCreate(Bundle savedInstanceState) {
...
// Create an AdsLoader.
ImaSdkSettings settings = sdkFactory.createImaSdkSettings();
adsLoader = sdkFactory.createAdsLoader(this, settings, adDisplayContainer);
// Add listeners for when ads are loaded and for errors.
adsLoader.addAdErrorListener(
new AdErrorEvent.AdErrorListener() {
/** An event raised when there is an error loading or playing ads. */
@Override
public void onAdError(AdErrorEvent adErrorEvent) {
Log.i(LOGTAG, "Ad Error: " + adErrorEvent.getError().getMessage());
resumeContent();
}
});
adsLoader.addAdsLoadedListener(
new AdsLoader.AdsLoadedListener() {
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
// Ads were successfully loaded, so get the AdsManager instance. AdsManager has
// events for ad playback and errors.
adsManager = adsManagerLoadedEvent.getAdsManager();
// Attach event and error event listeners.
adsManager.addAdErrorListener(
new AdErrorEvent.AdErrorListener() {
/** An event raised when there is an error loading or playing ads. */
@Override
public void onAdError(AdErrorEvent adErrorEvent) {
Log.e(LOGTAG, "Ad Error: " + adErrorEvent.getError().getMessage());
String universalAdIds =
Arrays.toString(adsManager.getCurrentAd().getUniversalAdIds());
Log.i(
LOGTAG,
"Discarding the current ad break with universal "
+ "ad Ids: "
+ universalAdIds);
adsManager.discardAdBreak();
}
});
}
});
11. Processar eventos de anúncio do IMA
Detectar eventos de anúncio do IMA com
AdsManager.addAdEventListener Usando uma instrução switch, configure ações para os seguintes eventos do IMA:
O snippet de código inclui comentários com mais informações sobre como usar os eventos. Quando o
eventos estiverem configurados, poderá chamar
AdsManager.init()
adsLoader.addAdsLoadedListener(
new AdsLoader.AdsLoadedListener() {
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
...
adsManager.addAdEventListener(
new AdEvent.AdEventListener() {
/** Responds to AdEvents. */
@Override
public void onAdEvent(AdEvent adEvent) {
if (adEvent.getType() != AdEvent.AdEventType.AD_PROGRESS) {
Log.i(LOGTAG, "Event: " + adEvent.getType());
}
// These are the suggested event types to handle. For full list of
// all ad event types, see AdEvent.AdEventType documentation.
switch (adEvent.getType()) {
case LOADED:
// AdEventType.LOADED is fired when ads are ready to play.
// This sample app uses the sample tag
// single_preroll_skippable_ad_tag_url that requires calling
// AdsManager.start() to start ad playback.
// If you use a different ad tag URL that returns a VMAP or
// an ad rules playlist, the adsManager.init() function will
// trigger ad playback automatically and the IMA SDK will
// ignore the adsManager.start().
// It is safe to always call adsManager.start() in the
// LOADED event.
adsManager.start();
break;
case CONTENT_PAUSE_REQUESTED:
// AdEventType.CONTENT_PAUSE_REQUESTED is fired when you
// should pause your content and start playing an ad.
pauseContentForAds();
break;
case CONTENT_RESUME_REQUESTED:
// AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad
// you should play your content.
resumeContent();
break;
case ALL_ADS_COMPLETED:
// Calling adsManager.destroy() triggers the function
// VideoAdPlayer.release().
adsManager.destroy();
adsManager = null;
break;
case CLICKED:
// When the user clicks on the Learn More button, the IMA SDK fires
// this event, pauses the ad, and opens the ad's click-through URL.
// When the user returns to the app, the IMA SDK calls the
// VideoAdPlayer.playAd() function automatically.
break;
default:
break;
}
}
});
AdsRenderingSettings adsRenderingSettings =
ImaSdkFactory.getInstance().createAdsRenderingSettings();
adsManager.init(adsRenderingSettings);
}
12. Processar a alternância entre anúncios e conteúdo
Nesta seção, crie o pauseContentForAds e o resumeContent
métodos mencionados nas etapas anteriores. Esses métodos vão reutilizar o player para jogar
conteúdo e anúncios. Você precisará acompanhar a posição do conteúdo para
retome a reprodução após o intervalo de anúncio.
/** Main activity. */
public class MyActivity extends AppCompatActivity {
...
private void pauseContentForAds() {
Log.i(LOGTAG, "pauseContentForAds");
savedPosition = videoPlayer.getCurrentPosition();
videoPlayer.stopPlayback();
// Hide the buttons and seek bar controlling the video view.
videoPlayer.setMediaController(null);
}
private void resumeContent() {
Log.i(LOGTAG, "resumeContent");
// Show the buttons and seek bar controlling the video view.
videoPlayer.setVideoPath(SAMPLE_VIDEO_URL);
videoPlayer.setMediaController(mediaController);
videoPlayer.setOnPreparedListener(
mediaPlayer -> {
if (savedPosition > 0) {
mediaPlayer.seekTo(savedPosition);
}
mediaPlayer.start();
});
videoPlayer.setOnCompletionListener(
mediaPlayer -> videoAdPlayerAdapter.notifyImaOnContentCompleted());
}
}
13. Solicitar anúncios
Agora, adicione o método requestAds para criar um
AdsRequest
e use-o para chamar AdsLoader.requestAds().
/** Main activity. */
public class MyActivity extends AppCompatActivity {
...
private void requestAds(String adTagUrl) {
// Create the ads request.
AdsRequest request = sdkFactory.createAdsRequest();
request.setAdTagUrl(adTagUrl);
request.setContentProgressProvider(
() -> {
if (videoPlayer.getDuration() <= 0) {
return VideoProgressUpdate.VIDEO_TIME_NOT_READY;
}
return new VideoProgressUpdate(
videoPlayer.getCurrentPosition(), videoPlayer.getDuration());
});
// Request the ad. After the ad is loaded, onAdsManagerLoaded() will be called.
adsLoader.requestAds(request);
}
}
Pronto! Agora você solicita e exibe anúncios com o SDK do IMA. Para saber mais sobre recursos do SDK, consulte os outros guias ou a no GitHub.