Premiers pas avec l'extension IMA d'ExoPlayer

ExoPlayer est un lecteur multimédia au niveau de l'application pour Android. Ce guide vous explique comment utiliser l'extension IMA d'ExoPlayer, qui intègre le SDK IMA DAI, pour demander et lire un flux multimédia comportant à la fois des annonces et du contenu.

Voici quelques-uns des avantages de cette extension:

• Il simplifie le code nécessaire à l'intégration d'IMA aux fonctionnalités.
• Réduction du temps de développement nécessaire pour passer aux nouvelles versions d'IMA

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

Compatibilité avec les flux de l'extension ExoPlayer-IMA
	Diffusion en direct	Flux de vidéo à la demande
HLS
DASH

Les diffusions en direct DASH sont compatibles avec ExoPlayer-IMA version 1.1.0 ou ultérieure.

Basé sur le guide ExoPlayer, ce guide explique comment créer une application complète et intégrer l'extension. Consultez ExoPlayerExample sur GitHub pour obtenir un exemple d'application exemple complète.

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

Conditions préalables

• Android Studio
• AndroidX Media3 ExoPlayer version 1.0.0 ou ultérieure pour l'insertion dynamique d'annonces

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 Aucune activité.
• Cliquez sur Suivant.

• Sur la page Configure your project (Configurer votre projet), nommez votre projet et sélectionnez Java comme langage.

  Remarque :Le SDK IMA DAI est compatible avec Kotlin. Cependant, l'exemple traité dans ce guide utilise Java.

• Cliquez sur Terminer.

Ajouter l'extension IMA d'ExoPlayer à votre projet

Ajoutez des importations pour l'extension dans le fichier build.gradle au niveau de l'application dans la section dependencies.

Configurez votre application et activez multidex. En raison de la taille de l'extension, cette opération est obligatoire pour les applications avec minSdkVersion défini sur Android 4.4W (niveau d'API 20) ou version antérieure.

Exemple :

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

Ajoutez les autorisations utilisateur requises par le SDK IMA DAI 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 DAI 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 DAI nécessitent une déclaration d'intention explicite pour ouvrir les liens Web. Ajoutez l'extrait suivant au fichier manifeste de votre application afin d'activer les clics sur les annonces (les utilisateurs cliquant sur le bouton En savoir plus).

Remarque :Les futures versions du SDK IMA DAI incluront automatiquement ces déclarations et seront fusionnées avec le fichier manifeste de votre application.

  <?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>

Configurer l'interface utilisateur d'ExoPlayer

Créez l'objet PlayerView qui sera utilisé par ExoPlayer.

Remplacez androidx.constraintlayout.widget.ConstraintLayout par LinearLayout, ce qui est recommandé pour l'extension IMA d'ExoPlayer.

Exemple :

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    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:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

Ajouter vos paramètres de flux

Consultez la page Exemples de flux IMA afin d'obtenir des exemples d'éléments de flux permettant de tester votre projet. Consultez également la section Ad Manager concernant l'insertion dynamique d'annonces pour savoir comment configurer vos propres flux.

Cette étape explique comment configurer un flux en direct, mais l'extension IMA d'ExoPlayer est également compatible avec les flux de vidéo à la demande pour l'insertion dynamique d'annonces. Consultez l'étape concernant les flux de vidéo à la demande (VOD) afin de connaître les modifications nécessaires à votre application pour gérer les flux de vidéo à la demande.

Importer l'extension IMA d'ExoPlayer

Ajoutez les instructions d'importation pour l'extension ExoPlayer.

Ajoutez les variables privées suivantes à MyActivity.java:

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

Ajoutez la clé d'élément du flux HLS Big Buck Bunny (Live) pour effectuer un test avec ce flux. D'autres flux sont disponibles à tester sur l'exemple de page de flux d'IMA.

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

Exemple :

app/src/main/java/com/example/project name/MyActivity.java

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

Créer une instance adsLoader

Écrasez la méthode onCreate pour rechercher PlayerView et rechercher un AdsLoader.State enregistré, qui peut être utilisé lors du lancement de l'objet adsLoader.

Activez également multidex si le nombre de méthodes et minSdkVersion de votre application l'exigent (comme expliqué à l'étape 2).

Exemple :

app/src/main/java/com/example/project name/MyActivity.java

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

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

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

}

Ajouter des méthodes pour initialiser le lecteur

Ajoutez une méthode pour initialiser le lecteur et procédez comme suit:

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

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 dans Google Ad Manager est une instance d'insertion d'annonces côté serveur.
• L'implémentation de l'extension IMA d'ExoPlayer dans ce guide est conçue pour fonctionner spécifiquement avec l'insertion dynamique d'annonces Ad Manager. Les extensions IMA d'ExoPlayer sont également compatibles avec d'autres instances SSAI, comme Google Cloud Platform, qui ne sont pas décrites dans ce guide.

Exemple :

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

    return adsLoaderBuilder.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 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);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

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

Ajouter une méthode pour libérer le joueur

Ajoutez une méthode pour libérer le lecteur dans la séquence suivante:

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

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  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 de joueur

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

Pour prendre en charge le SDK Android 24 ou version ultérieure:

• onStart()
• onStop()

Pour prendre en charge les versions du SDK Android antérieures à la version 24 : - onResume() - onPause()

onStart() et onResume() sont mappés à playerView.onResume(), et onStop() et onPause() à playerView.onPause().

Important :Cet exemple vise à être compatible à la fois avec le SDK Android version 24 ou ultérieure et avec les versions antérieures à la version 24. Utilisez onStart()/onStop() pour la compatibilité avec le SDK Android version 24 ou ultérieure, et onResume()/onPause() pour les versions antérieures à cette version.

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

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  @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 de vidéo à la demande (facultatif)

Si votre application doit lire du contenu de vidéo à la demande avec des annonces, procédez comme suit:

1. Ajoutez des éléments CMS ID et Video ID pour un flux de test de vidéo à la demande.
2. Créez un URI de vidéo à la demande SSAI à l'aide de ImaServerSideAdInsertionUriBuilder().
3. Utilisez ce nouvel URI comme élément multimédia du lecteur.

app/src/main/java/com/example/project name/MyActivity.java

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 SAMPLE_CMS_ID = "2548831";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

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

Et voilà ! Vous demandez et lisez maintenant un flux multimédia avec l'extension IMA d'ExoPlayer. Consultez les exemples d'insertion dynamique d'annonces Android sur GitHub pour obtenir le code complet.