Premiers pas avec l'extension IMA d'ExoPlayer

ExoPlayer est un lecteur multimédia Android. Ce guide vous explique comment utiliser l'extension ExoPlayer IMA. Cette extension utilise le SDK IMA DAI pour demander et lire des flux multimédias avec des annonces et du contenu.

Voici les avantages de l'extension :

• Simplifie le code nécessaire à l'intégration des fonctionnalités IMA.
• Réduit le temps nécessaire pour passer aux nouvelles versions d'IMA.

L'extension IMA ExoPlayer est compatible avec les protocoles de streaming HLS et DASH. Voici un récapitulatif :

Compatibilité des flux de l'extension ExoPlayer-IMA
	Diffusion en direct	Flux VOD
HLS
DASH

ExoPlayer-IMA version 1.1.0 et ultérieure est compatible avec les diffusions en direct DASH.

Ce guide utilise le guide ExoPlayer pour vous aider à créer une application complète et à intégrer l'extension. Pour obtenir un exemple d'application complet, consultez ExoPlayerExample sur GitHub.

Important : L'extension ExoPlayer IMA nécessite ExoPlayer. Si vous préférez un autre lecteur, suivez le guide de démarrage pour intégrer le SDK IMA DAI à votre application.

Prérequis

• Android Studio
• AndroidX Media3 ExoPlayer version 1.0.0 ou ultérieure pour la compatibilité avec DAI.

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 Choose your project (Choisir votre projet), sélectionnez le modèle No Activity (Aucune activité).
4. Cliquez sur Suivant.
5. Sur la page Configurer votre projet, donnez un nom à votre projet et sélectionnez Java comme langage. Remarque : Le SDK IMA DAI fonctionne avec Kotlin, mais ce guide utilise des exemples Java.

• Cliquez sur Terminer.

Ajouter l'extension ExoPlayer IMA à votre projet

Pour ajouter l'extension ExoPlayer IMA, procédez comme suit :

1. Incluez les importations suivantes dans la section dependencies du fichier build.gradle de votre application :

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       implementation "androidx.media3:media3-ui:$media3_version"
       implementation "androidx.media3:media3-exoplayer:$media3_version"
       implementation "androidx.media3:media3-exoplayer-hls:$media3_version"
       implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation "androidx.media3:media3-exoplayer-ima:$media3_version"
   }
   build.gradle
   

2. Ajoutez les autorisations utilisateur dont le SDK IMA DAI a besoin pour demander des annonces :

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

Configurer l'UI ExoPlayer

Pour configurer l'UI ExoPlayer :

1. Créez l'objet PlayerView pour ExoPlayer.

2. Remplacez la vue androidx.constraintlayout.widget.ConstraintLayout par une vue LinearLayout, comme recommandé par l'extension ExoPlayer IMA :

   <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">
   
       <androidx.media3.ui.PlayerView
           android:id="@+id/player_view"
           android:fitsSystemWindows="true"
           android:layout_width="match_parent"
           android:layout_height="wrap_content" />
   
       <!-- UI element for viewing SDK event log -->
       <TextView
           android:id="@+id/logText"
           android:gravity="bottom"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:maxLines="100"
           android:scrollbars="vertical"
           android:textSize="@dimen/font_size">
       </TextView>
   
   </LinearLayout>
   activity_my.xml
   

Ajouter vos paramètres de flux

Consultez la page des exemples de flux IMA pour obtenir des exemples de composants de flux permettant de tester votre projet. Pour configurer vos propres flux, consultez la section Ad Manager sur l'insertion dynamique d'annonces.

Cette étape permet de configurer une diffusion en direct. L'extension ExoPlayer IMA est également compatible avec les flux VOD DAI. Pour savoir quelles modifications votre application doit apporter pour les flux VOD, consultez l'étape pour les flux vidéo à la demande (VOD).

Importer l'extension ExoPlayer IMA

1. Ajoutez les instructions d'importation suivantes pour l'extension ExoPlayer :

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.net.Uri;
   import android.os.Bundle;
   import android.text.method.ScrollingMovementMethod;
   import android.util.Log;
   import android.widget.TextView;
   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.ImaServerSideAdInsertionMediaSource;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
   import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
   import androidx.media3.ui.PlayerView;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. Dans MyActivity.java, ajoutez ces variables privées :

   • PlayerView
   • ExoPlayer
   • ImaServerSideAdInsertionMediaSource.AdsLoader
   • ImaServerSideAdInsertionMediaSource.AdsLoader.State

   Pour effectuer un test avec le flux HLS Big Buck Bunny (Live), ajoutez sa clé d'élément. Vous trouverez d'autres flux à tester sur la page d'exemples de flux de l'IMA.

3. Créez une constante KEY_ADS_LOADER_STATE pour enregistrer et récupérer l'état AdsLoader :

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
     private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
     private static final String LOG_TAG = "ImaExoPlayerExample";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

Créer une instance adsLoader

Remplacez la méthode onCreate. Dans celui-ci, recherchez PlayerView et vérifiez si un AdsLoader.State est enregistré. Vous pouvez utiliser cet état lorsque vous initialisez l'objet adsLoader.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_my);

  // Initialize the IMA SDK as early as possible when the app starts. If your app already
  // overrides Application.onCreate(), call this method inside the onCreate() method.
  // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
  ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

  playerView = findViewById(R.id.player_view);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

Important : Pour améliorer les temps de chargement IMA, appelez la méthode ImaSdkFactory.initialize() le plus tôt possible dans le cycle de vie de l'application. Appeler la méthode tôt permet à IMA de disposer d'un maximum de temps pour charger les ressources nécessaires avant la première demande de flux. L'appel de méthode ImaSdkFactory.initialize() accepte une instance ImaSdkSettings. Veillez à utiliser les mêmes valeurs de paramètres ici et lorsque vous créez une instance AdsLoader. Cet exemple utilise la méthode d'assistance getImaSdkSettings() pour s'assurer que les valeurs des paramètres sont identiques. Pour en savoir plus, consultez le guide sur l'optimisation du temps de chargement IMA.

Ajouter des méthodes pour initialiser le lecteur

Ajoutez une méthode pour initialiser le lecteur. Cette méthode doit effectuer les opérations suivantes :

• Créez une instance AdsLoader.
• Créez le sous-réseau ExoPlayer.
• Créez un MediaItem à l'aide de la clé de l'élément de la diffusion en direct.
• Définissez le MediaItem pour votre lecteur.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer 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 stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

Remarque : Cette section utilise des méthodes dont les noms font référence à des concepts d'insertion d'annonces côté serveur (SSAI).

• L'insertion dynamique d'annonces Google Ad Manager est un exemple d'SSAI.
• L'extension ExoPlayer IMA de ce guide fonctionne spécifiquement avec l'insertion dynamique d'annonces Ad Manager. L'extension ExoPlayer IMA est également compatible avec différentes solutions SSAI.

Ajouter une méthode pour libérer le lecteur

Ajoutez une méthode pour libérer le lecteur. Cette méthode doit effectuer les actions suivantes dans l'ordre :

• Définissez les références du lecteur sur "null" et libérez les ressources du lecteur.
• Libérez l'état adsLoader.

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

Gérer les événements du lecteur

Pour gérer les événements du lecteur, créez des rappels pour les événements du cycle de vie de l'activité afin de gérer la lecture du flux.

Pour le niveau d'API Android 24 et versions ultérieures, utilisez les méthodes suivantes :

• onStart()
• onStop()

Pour les niveaux d'API Android antérieurs à 24, utilisez les méthodes suivantes :

• onResume()
• onPause()

Les méthodes onStart() et onResume() correspondent à playerView.onResume(), tandis que onStop() et onPause() correspondent à playerView.onPause().

Point clé : Cet exemple est compatible avec la version 24 et les versions antérieures du SDK Android. Utilisez onStart()/onStop() pour le SDK Android version 24 ou ultérieure, et onResume()/onPause() pour les versions antérieures à 24.

Cette étape utilise également l'événement onSaveInstanceState() pour enregistrer adsLoaderState.

@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
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

Configuration du flux de vidéo à la demande (facultatif)

Si votre application doit lire du contenu VOD avec des annonces, procédez comme suit :

1. Ajoutez un CMS ID et un Video ID pour un flux de vidéo à la demande. Pour les tests, utilisez les paramètres de flux suivants :
   • ID dans le CMS : "2548831"
   • ID de la vidéo : "tears-of-steel"

2. Créez un URI VOD SSAI à l'aide de la méthode ImaServerSideAdInsertionUriBuilder() :

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. Définissez le nouvel URI du flux VOD comme élément multimédia de votre lecteur à l'aide de la méthode MediaItem.fromUri().

Si l'opération réussit, vous pouvez demander et lire un flux multimédia avec l'extension ExoPlayer IMA. Pour obtenir l'exemple complet, consultez les exemples d'insertion dynamique d'annonces Android sur GitHub.