Premiers pas avec l'extension IMA d'Exoplayer

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 la classe Extension IMA d'ExoPlayer. Si vous souhaitez consulter ou suivre un exemple d'intégration terminé, téléchargez le BasicExample de GitHub

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

Avant de commencer, vous devez 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:

  1. Lancez Android Studio.
  2. Sélectionnez Start a new Android Studio project (Démarrer un nouveau projet Android Studio).
  3. Sur la page Sélectionner votre projet, sélectionnez le modèle Activité vide.
  4. Cliquez sur Suivant.
  5. Sur la page Configure your project (Configurer votre projet), attribuez un nom à votre projet et sélectionnez "Java" comme langage.
  6. 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 des importations pour l'extension au les 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 la valeur de minSdkVersion est inférieure ou égale à 20. Ajoutez également un nouveau compileOptions pour spécifier les informations de compatibilité des versions 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'

    ...
}

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 de la Le SDK IMA nécessite une déclaration d'intention explicite pour ouvrir les liens Web. Ajoutez l'extrait suivant à le fichier manifeste de votre application afin d'activer les clics sur les annonces (les utilisateurs cliquant sur le bouton En savoir plus ). <ph type="x-smartling-placeholder"> 
  <?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 de l'UI de l'annonce

Créez la vue à utiliser comme ExoPlayer PlayerView en créant un StyledPlayerView. avec un ID approprié. Modifiez également le androidx.constraintlayout.widget.ConstraintLayout en 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. Ajoutez l'URL de contenu et l'URL du tag d'emplacement publicitaire à la demande d'annonces

Ajoutez des entrées à strings.xml pour stocker votre URL de contenu et l'URL de votre tag d'emplacement publicitaire 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. Importer l'extension IMA d'ExoPlayer

Ajoutez les instructions d'importation pour l'extension ExoPlayer. Ensuite, mettez à jour MainActivity pour étendre Activity en ajoutant des variables privées pour le PlayerView, le SimpleExoPlayer et le 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. Créer une instance adsLoader

Remplacez la méthode onCreate et ajoutez les attributions de variables requises pour créer un Nouvel objet adsLoader avec l'URL du tag d'emplacement publicitaire.

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. Initialiser et libérer le lecteur

Ajout de méthodes pour initialiser et libérer le lecteur. Lors de la phase d'initialisation, , créez l'SimpleExoPlayer. Ensuite, créez le AdsMediaSource. et le définir sur le lecteur.

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. Gérer les événements de joueur

Enfin, créez des rappels pour les événements de cycle de vie du joueur:

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
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();
  }

  ...

}

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.