ExoPlayer è un media player a livello di applicazione per Android. Questa guida illustra come utilizzare l'estensione IMA ExoPlayer, che aggrega l'SDK IMA DAI, per richiedere e riprodurre uno stream multimediale con annunci e contenuti.
Ecco alcuni dei vantaggi dell'estensione:
- Semplifica il codice necessario per integrare l'IMA con le funzionalità.
- Riduce il tempo di sviluppo necessario per l'aggiornamento alle nuove versioni di IMA.
L'estensione IMA di ExoPlayer supporta i protocolli di streaming HLS e DASH. Ecco un riepilogo:
Supporto stream estensione ExoPlayer-IMA | ||
---|---|---|
Live streaming | Stream VOD | |
HLS | ||
PANORAMICA |
I live streaming DASH sono supportati su ExoPlayer-IMA versione 1.1.0 e successive.
Questa guida si basa sulla guida di ExoPlayer e spiega come creare un'app completa e integrare l'estensione. Consulta
ExoPlayerExample
di
GitHub per un esempio con
un'app di esempio completa.
Prerequisiti
- Android Studio
- AndroidX Media3 ExoPlayer versione 1.0.0 o successiva per il supporto DAI.
Crea un nuovo progetto Android Studio
Per creare il tuo progetto Android Studio, procedi nel seguente modo:
- Avvia Android Studio.
- Seleziona Avvia un nuovo progetto Android Studio.
- Nella pagina Scegli il tuo progetto, seleziona il modello Nessuna attività.
- Fai clic su Avanti.
Nella pagina Configura il tuo progetto, assegna un nome al progetto e seleziona Java per il linguaggio.
Fai clic su Fine.
Aggiungi l'estensione IMA di ExoPlayer al tuo progetto
Aggiungi importazioni per l'estensione al file build.gradle a livello di applicazione
nella sezione dependencies
.
Configura e attiva
multidex. Questa operazione è necessaria a causa
delle dimensioni dell'estensione ed è obbligatoria per le app con minSdkVersion
impostato
su Android 4.4W (livello API
20) o versioni precedenti.
Esempio:
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' }
Aggiungi le autorizzazioni utente richieste dall'SDK IMA DAI per richiedere annunci:
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>
Aggiungi dichiarazioni di intent
Se la tua app ha come target Android 11 (livello API 30) o versioni successive, le versioni attuali e recenti dell'SDK IMA DAI richiedono una dichiarazione esplicita di intenti per aprire i link web. Aggiungi il seguente snippet al file manifest dell'app per attivare i clickthrough degli annunci (gli utenti che fanno clic sul pulsante Scopri di più).
<?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>
Imposta UI di ExoPlayer
Crea l'oggetto PlayerView
che deve essere utilizzato da ExoPlayer.
Modifica androidx.constraintlayout.widget.ConstraintLayout
in un
LinearLayout
, metodo consigliato per l'estensione IMA di ExoPlayer.
Esempio:
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>
Aggiungi i parametri dello stream
Consulta la pagina del flusso di esempio di esempio IMA per gli asset di esempio per il flusso di dati per testare il progetto. Consulta anche la sezione di Ad Manager relativa all'inserimento di annunci dinamici per informazioni su come configurare i tuoi stream.
Questo passaggio illustra la configurazione di un live streaming, ma l'estensione IMA di ExoPlayer supporta anche gli stream DAI VOD. Consulta la procedura relativa agli stream di video on demand (VOD) per conoscere le modifiche necessarie alla tua app per gestire gli stream VOD.
Importa l'estensione IMA di ExoPlayer
Aggiungi le istruzioni di importazione per l'estensione ExoPlayer.
Aggiungi le seguenti variabili private a MyActivity.java
:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
Aggiungi la chiave asset dello stream HLS di Big Buck Bunny (live) da testare con questo stream. Sono disponibili altri stream da testare nella pagina di esempio dello stream dell'IMA.
Crea una costante KEY_ADS_LOADER_STATE
per salvare e recuperare lo stato AdsLoader
.
Esempio:
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; }
Crea un'istanza adsLoader
Sovrascrivi il metodo onCreate
per trovare PlayerView
e verificare se è presente un AdsLoader.State
salvato, che può essere utilizzato all'avvio dell'oggetto adsLoader
.
Inoltre, abilita il multidex se richiesto dal conteggio dei metodi della tua app e minSdkVersion
(come spiegato nel
passaggio 2).
Esempio:
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); } } } }
Aggiungi metodi per inizializzare il player
Aggiungi un metodo per inizializzare il player e procedi nel seguente modo:
- Crea un'istanza
AdsLoader
. - Crea il
ExoPlayer
. - Crea un
MediaItem
con la chiave asset del live streaming. - Imposta
MediaItem
sul tuo player.
Esempio:
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); } }
Aggiungi un metodo per rilasciare il player
Aggiungi un metodo per rilasciare il player in questa sequenza:
- Imposta i riferimenti del player su null e rilascia le risorse del player.
- Rilascia lo stato di
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(); }
Gestire gli eventi dei giocatori
Infine, crea callback per gli eventi del ciclo di vita dell'attività per gestire la riproduzione dello stream.
Per supportare l'SDK Android 24 o versioni successive:
Per supportare versioni dell'SDK Android precedenti alla 24:
- onResume()
- onPause()
onStart()
e onResume()
vengono mappati a playerView.onResume()
, mentre onStop()
e
onPause()
vengono mappati a playerView.onPause()
.
Questo passaggio utilizza anche l'evento onSaveInstanceState()
per tentare di salvare 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()); } } ... }
Configurazione dello stream VOD (facoltativo)
Se la tua app è necessaria per riprodurre contenuti VOD con annunci, dovrai:
- Aggiungi
CMS ID
eVideo ID
per uno stream di prova VOD. - Crea un URI VOD SSAI utilizzando
ImaServerSideAdInsertionUriBuilder()
. - Utilizza questo nuovo URI come elemento multimediale del player.
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); }
È tutto. Stai richiedendo e riproducendo uno stream multimediale con l'estensione IMA di ExoPlayer. Dai un'occhiata agli esempi di DAI per Android su GitHub per il codice completo.