Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA demander des annonces <ph type="x-smartling-placeholder"></ph> compatible avec la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA côté client, vous gardez le contrôle de la lecture du contenu vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées un lecteur vidéo distinct placé au-dessus du lecteur vidéo de contenu de l'application.
Ce guide explique comment intégrer le SDK IMA dans un projet Android Studio vide à l'aide de dans Android VideoView pour afficher du contenu et des annonces. Pour suivre un exemple terminé intégration, téléchargez le BasicExample de GitHub
<ph type="x-smartling-placeholder">Présentation d'IMA côté client
L'implémentation d'IMA côté client implique quatre composants principaux du SDK, illustrés dans ce guide:
AdDisplayContainer: Objet conteneur dans lequel les annonces sont affichées.AdsLoader: Objet qui demande des annonces et gère les événements provenant des réponses aux demandes d'annonces. Vous ne devez instancier un chargeur d'annonces que vous pouvez réutiliser tout au long de la durée de vie de l'application ;AdsRequest: Objet qui définit une demande d'annonces. Les demandes d'annonces spécifient l'URL du tag d'emplacement publicitaire VAST, ainsi que des paramètres supplémentaires, tels que les dimensions de l'annonce.AdsManager: Objet qui contient la réponse à la demande d'annonce, contrôle la lecture des annonces et écoute l'annonce déclenchés par le SDK.
Prérequis
1. Créer un projet Android Studio
Pour créer votre projet Android Studio, procédez comme suit:
- Lancez Android Studio.
- Sélectionnez Start a new Android Studio project (Démarrer un nouveau projet Android Studio).
- Sur la page Sélectionner votre projet, sélectionnez le modèle Activité vide.
- Cliquez sur Suivant.
- Sur la page Configure your project (Configurer votre projet), attribuez un nom à votre projet et sélectionnez "Java" comme langage.
- Cliquez sur Terminer.
2. Ajouter le SDK IMA à votre projet
Dans le fichier build.gradle au niveau de l'application, commencez par ajouter les importations pour le SDK IMA au fichier
les dépendances. Compte tenu de la taille du SDK IMA, implémentez et activez multidex ici. Ce
est nécessaire pour les applications dont la valeur de minSdkVersion est inférieure ou égale à 20. Ajoutez également
compileOptions pour spécifier les informations de compatibilité des versions 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. Ajouter les autorisations requises pour le SDK IMA
Ajoutez les autorisations utilisateur requises par le SDK IMA pour demander des annonces.
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. Mettre à jour la mise en page de l'application
Mettez à jour la mise en page de l'application pour inclure un VideoView permettant de lire le contenu et
annonces.
<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. Importer IMA dans l'activité principale
Ajoutez les instructions d'importation pour le SDK IMA. Ensuite, mettez à jour
MyActivity pour étendre AppCompatActivity. La
La classe AppCompatActivity permet la prise en charge des nouvelles fonctionnalités de la plate-forme sur des anciennes plates-formes.
Appareils Android Ajoutez ensuite un ensemble de variables privées qui seront utilisées dans l'application.
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. Créer la classe VideoAdPlayerAdapter
Créez une classe VideoAdPlayerAdapter avec VideoView.
et nous l'adapterons
<ph type="x-smartling-placeholder"></ph>
VideoAdPlayer
. Cette classe gérera la lecture du contenu et des annonces, et contiendra l'ensemble des
qu'un lecteur vidéo doit implémenter pour être utilisés par le SDK 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. Remplacer les méthodes VideoAdPlayer
Remplacez les méthodes VideoAdPlayer suivantes:
La méthode playAd() définit l'URL du contenu ou de l'annonce, ainsi qu'un écouteur pour démarrer
une fois le contenu chargé.
/** 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. Configurer le suivi des annonces
Pour que des événements
d'annonce soient enregistrés,
VideoAdPlayerCallback.onAdProgress doit être appelé lors de la diffusion du contenu et des annonces. Pour ce faire, configurez un minuteur afin d'appeler onAdProgress() à un intervalle défini.
/** 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. Lancer le SDK IMA dans la méthode onCreate
Écrasez la méthode onCreate et ajoutez les attributions de variables requises pour lancer
IMA. Au cours de cette étape, vous allez créer les éléments suivants:
ImaSdkSettingsAdsLoader
Cette étape crée également un VideoAdPlayerAdapter, une classe que vous créerez plus tard
dans ce guide.
Enfin, configurez le bouton de lecture pour demander des annonces, puis masquez-le lorsque l'utilisateur clique dessus.
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. Ajouter des écouteurs AdsLoader
Ajoutez des écouteurs pour addAdErrorListener et
addAdsLoadedListener Dans AdsLoadedListener, créez le
AdsManager, puis configurez l'écouteur d'erreurs 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. Gérer les événements d'annonce IMA
Écoutez les événements d'annonce IMA
AdsManager.addAdEventListener À l'aide d'une instruction switch, configurez des actions pour les événements IMA suivants:
L'extrait de code inclut des commentaires contenant plus d'informations sur l'utilisation des événements. Une fois que
sont configurés, vous pouvez appeler
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. Gérer le basculement entre les annonces et le contenu
Dans cette section, créez les éléments pauseContentForAds et resumeContent.
référencées dans les étapes précédentes. Ces méthodes réutiliseront
le lecteur pour jouer
pour le contenu et les annonces. Vous devrez suivre la position du contenu afin de
reprendre la lecture après la coupure publicitaire.
/** 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. Demander des annonces
Ajoutez maintenant la méthode requestAds pour créer
AdsRequest
et l'utiliser pour appeler 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);
}
}
Et voilà ! Vous demandez et affichez à présent des annonces avec le SDK IMA. Pour découvrir d'autres les fonctionnalités du SDK, consultez les autres guides ou la exemples sur GitHub.