Les SDK IMA permettent d'intégrer facilement des annonces multimédias à vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server conforme à la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK côté client IMA, 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 dans un lecteur vidéo distinct situé 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 l'extension IMA ExoPlayer. Si vous souhaitez consulter ou suivre un exemple d'intégration terminé, téléchargez BasicExample sur GitHub.
Présentation de l'IMA côté client
L'implémentation d'IMA côté client implique quatre composants principaux du SDK, qui sont illustrés dans ce guide:
AdDisplayContainer
: objet de conteneur qui spécifie où IMA affiche les éléments d'interface utilisateur de l'annonce et mesure la visibilité, y compris Active View et Open Measurement.AdsLoader
: objet qui demande des annonces et gère les événements à partir des réponses aux requêtes d'annonces. Vous ne devez instancier qu'un seul chargeur d'annonces, qui peut être réutilisé tout au long de la durée de vie de l'application.AdsRequest
: objet qui définit une requête d'annonces. Les requêtes 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 contenant la réponse à la demande d'annonces, qui contrôle la lecture des annonces et écoute les événements d'annonces déclenchés par le SDK.
Prérequis
Avant de commencer, vous devez disposer d'Android Studio 3.0 ou version ultérieure.
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 Choose your project (Choisir votre projet), sélectionnez le modèle Empty Activity (Activité vide).
- Cliquez sur Suivant.
- Sur la page Configurer votre projet, nommez votre projet et sélectionnez Java comme langage.
- Cliquez sur Terminer.
2. Ajouter l'extension IMA d'ExoPlayer à votre projet
Tout d'abord, dans le fichier build.gradle au niveau de l'application, ajoutez les importations de l'extension à la section des dépendances. En raison de la taille de l'extension IMA d'ExoPlayer, implémentez et activez multidex ici. Cela est nécessaire pour les applications dont minSdkVersion
est défini sur 20 ou moins.
Ajoutez également un compileOptions
pour spécifier les informations de compatibilité de la version Java.
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' ... }
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>
Ajouter des déclarations d'intent
Si votre application cible Android 11 (niveau d'API 30) ou une version ultérieure, les versions actuelles et récentes du SDK IMA nécessitent une déclaration explicite d'intention d'ouvrir des liens Web. Ajoutez l'extrait de code suivant au fichier manifeste de votre application pour activer les clics sur les annonces (les utilisateurs cliquent sur le bouton En savoir plus).<?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. Créer le conteneur d'UI de l'annonce
Créez la vue à utiliser comme PlayerView ExoPlayer en créant un objet StyledPlayerView
avec un ID approprié. Remplacez également androidx.constraintlayout.widget.ConstraintLayout
par LinearLayout
.
<?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. Ajouter l'URL de votre contenu et l'URL de la balise d'annonce pour la demande d'annonces
Ajoutez des entrées à strings.xml
pour stocker l'URL de votre contenu et l'URL de votre tag d'annonce VAST.
<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. Importer l'extension IMA d'ExoPlayer
Ajoutez les instructions d'importation pour l'extension ExoPlayer. Ensuite, mettez à jour la classe MainActivity
pour étendre Activity
en ajoutant des variables privées pour PlayerView
, SimpleExoPlayer
et ImaAdsLoader
.
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. Créer une instance adsLoader
Remplacez la méthode onCreate
et ajoutez les attributions de variables requises pour créer un objet adsLoader
avec l'URL de la balise publicitaire.
... 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. Initialiser et libérer le lecteur
Ajoutez des méthodes pour initialiser et libérer le lecteur. Dans la méthode d'initialisation, créez le SimpleExoPlayer
. Ensuite, créez le AdsMediaSource
et définissez-le sur le lecteur.
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. Gérer les événements du lecteur
Enfin, créez des rappels pour les événements de cycle de vie du lecteur:
onStart
onResume
onStop
onPause
onDestroy
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(); } ... }
Et voilà ! Vous demandez et affichez désormais des annonces avec le SDK IMA. Pour en savoir plus sur les fonctionnalités supplémentaires du SDK, consultez les autres guides ou les exemples sur GitHub.