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 pour intégrer les fonctionnalités IMA.
  • Réduit le temps nécessaire pour effectuer la mise à jour vers de nouvelles versions d'IMA.

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

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

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.

Prérequis

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 Configure your project (Configurer votre projet), nommez 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.9.1"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.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")
}

  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"/>

Configurer l'interface utilisateur ExoPlayer

Pour configurer l'interface utilisateur ExoPlayer, procédez comme suit :

  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>

Ajouter les paramètres de votre flux

Consultez la page de flux exemple IMA pour obtenir des exemples d'éléments de flux afin de tester votre projet. Pour configurer vos propres flux, consultez la section Ad Manager sur DAI.

Cette étape configure une diffusion en direct. L'extension ExoPlayer IMA est également compatible avec les flux VOD DAI. Pour savoir quelles modifications votre application doit apporter aux flux VOD, consultez l' étape concernant 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;

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

    Pour effectuer des tests avec le flux HLS Big Buck Bunny (Live), ajoutez sa clé d'élément. Vous trouverez d'autres flux à tester sur la page de flux exemple d'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;

Créer une instance adsLoader

Remplacez la méthode onCreate. Recherchez-y le PlayerView et vérifiez si un enregistré AdsLoader.State existe. 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;
}

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éer une instance AdsLoader.
  • Créer l'ExoPlayer.
  • Créer un MediaItem à l'aide de la clé d'élément du flux en direct.
  • Définir 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();
}

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();
}

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 :

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

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

Cette étape utilise également l' onSaveInstanceState() événement pour enregistrer le 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());
  }
}

Configuration du flux VOD (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 VOD. Pour les tests, utilisez les paramètres de flux suivants :
    • CMS ID: "2548831"
    • Video ID: "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();
}

  3. Définissez le nouvel URI de 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 Exemples Android DAI sur GitHub.