ExoPlayer est un Lecteur multimédia au niveau de l'application pour Android. Ce guide vous explique comment utiliser le Extension IMA d'ExoPlayer, qui encapsule le SDK IMA DAI, pour demander et lire un flux multimédia avec à la fois pour les annonces et pour le 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.
Ce guide est basé sur l'API ExoPlayer
guide, et montre
comment créer une application complète et intégrer l'extension. Consultez le
ExoPlayerExample
de
GitHub pour obtenir un exemple avec
une application exemple complète.
Prérequis
- Android Studio
- AndroidX Media3 ExoPlayer version 1.0.0 ou ultérieure pour l'insertion dynamique d'annonce de l'assistance.
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" pour la langue.
Cliquez sur Terminer.
Ajouter l'extension IMA d'ExoPlayer à votre projet
Ajouter des importations pour l'extension au fichier build.gradle au niveau de l'application
dans la section dependencies
.
Configurer et activer votre application
multidex : Cela est nécessaire en raison
à la taille de l'extension. Il est obligatoire pour les applications pour lesquelles minSdkVersion
est défini.
vers Android 4.4W (niveau d'API)
20) ou inférieure.
Exemple :
app/build.gradle
android { ... defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp" 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.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 actuelle et récente du SDK IMA DAI nécessitent une déclaration d'intention explicite . Ajoutez l'extrait suivant au fichier manifeste de votre application pour activer les clics sur les annonces (utilisateurs cliquant 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>
Configurer l'interface utilisateur d'ExoPlayer
Créez l'objet PlayerView
qui sera utilisé par ExoPlayer.
Remplacez androidx.constraintlayout.widget.ConstraintLayout
par un
LinearLayout
, 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
Voir l'exemple de flux IMA pour voir un exemple de flux pour tester votre projet. Consultez également la section Ad Manager sur Insertion dynamique d'annonces pour savoir comment configurer vos propres flux.
Cette étape explique comment configurer une diffusion en direct, mais l'IMA d'ExoPlayer est également compatible avec les flux de vidéo à la demande pour l'insertion dynamique d'annonces. Consultez l'étape concernant la vidéo à la demande (VOD) flux pour connaître les modifications dont votre application a besoin 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 tester cette clé. flux. Vous pouvez tester d'autres flux Exemple de page de flux d'IMA
Créez une constante KEY_ADS_LOADER_STATE
pour enregistrer et récupérer AdsLoader
.
de l'état.
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 élément
AdsLoader.State
qui peut être utilisée lors du lancement de l'objet adsLoader
.
Activez également multidex si le nombre de méthodes de votre application et minSdkVersion
l'exigent.
(comme expliqué dans
é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.
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 le flux lecture.
Pour prendre en charge le SDK Android 24 ou version ultérieure:
Pour prendre en charge les versions du SDK Android antérieures à la version 24:
– onResume()
- onPause()
onStart()
et onResume()
sont mappés avec playerView.onResume()
, onStop()
et
onPause()
est mappé sur playerView.onPause()
.
Cette étape utilise également
onSaveInstanceState()
pour tenter d'enregistrer 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 des contenus VOD avec des annonces, vous devez : les éléments suivants:
- Ajoutez des éléments
CMS ID
etVideo ID
pour un flux de test de vidéo à la demande. - Créez un URI de vidéo à la demande SSAI à l'aide de
ImaServerSideAdInsertionUriBuilder()
. - 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 ExoPlayer. l'extension IMA. Consultez des exemples d'insertion dynamique d'annonces Android GitHub pour obtenir le code complet.