ExoPlayer è un media player a livello di applicazione per Android. Questa guida mostra come utilizzare l'estensione IMA di ExoPlayer, che racchiude l'SDK DAI IMA, per richiedere e riprodurre uno stream multimediale con annunci e contenuti.
Ecco alcuni dei vantaggi dell'estensione:
- Semplifica il codice necessario per integrare IMA con le funzionalità.
- Riduci i tempi di sviluppo necessari per l'aggiornamento alle nuove versioni di IMA.
L'estensione ExoPlayer IMA supporta i protocolli di streaming HLS e DASH. Ecco un breve riepilogo:
Supporto per gli stream delle estensioni ExoPlayer-IMA | ||
---|---|---|
Live streaming | Stream VOD | |
HLS | ||
DASH |
I live streaming DASH sono supportati su ExoPlayer-IMA versione 1.1.0 e successive.
Questa guida si basa sulla guida di ExoPlayer e mostra come creare un'app completa e integrare l'estensione. Consulta ExoPlayerExample
su GitHub per un esempio con un'app di esempio completa.
Prerequisiti
- Android Studio
- AndroidX Media3 ExoPlayer versione 1.0.0 o successive per il supporto di DAI.
Creare un nuovo progetto Android Studio
Per creare il progetto Android Studio:
- 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 progetto, assegna un nome al progetto e seleziona Java come lingua.
Fai clic su Fine.
Aggiungere l'estensione ExoPlayer IMA al progetto
Aggiungi le importazioni per l'estensione al file build.gradle a livello di applicazione
nella sezione dependencies
.
Configura la tua app e attiva
multidex. Questo è necessario per le dimensioni dell'estensione ed è obbligatorio per le app con minSdkVersion
impostato su Android 4.4W (livello API 20) o versioni precedenti.
Ecco un 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 gli 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>
Aggiungere dichiarazioni di intenti
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 della tua app per attivare i clic sugli annunci (gli utenti 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>
Configurare l'interfaccia utente di ExoPlayer
Crea l'oggetto PlayerView
da utilizzare da ExoPlayer.
Cambia androidx.constraintlayout.widget.ConstraintLayout
in
LinearLayout
, che è consigliato per l'estensione IMA di ExoPlayer.
Ecco un 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 di streaming
Consulta la pagina dello stream di sample IMA per gli asset dello stream di sample per testare il tuo progetto. Consulta anche la sezione su Ad Manager relativa ai annunci dinamici per informazioni sulla configurazione dei tuoi stream.
Questo passaggio mostra la configurazione di un live streaming, ma l'estensione IMA di ExoPlayer supporta anche gli stream VOD DAI. Consulta il passaggio relativo agli stream di video on demand (VOD) per scoprire quali modifiche deve apportare la tua app per gestire gli stream VOD.
Importa l'estensione ExoPlayer IMA
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 Big Buck Bunny (Live) da testare con questo stream. Puoi testare altri stream nella pagina degli stream di esempio di IMA.
Crea una costante KEY_ADS_LOADER_STATE
per salvare e recuperare lo stato AdsLoader
.
Ecco un 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 controlla se è stato salvato un AdsLoader.State
, che può essere utilizzato all'avvio dell'oggetto adsLoader
.
Inoltre, abilita MultiDex se richiesto dal numero di metodi e da minSdkVersion
(come spiegato nel
passaggio 2).
Ecco un 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 ed esegui le seguenti operazioni:
- Crea un'istanza
AdsLoader
. - Crea il
ExoPlayer
. - Crea un
MediaItem
con la chiave asset del live streaming. - Imposta
MediaItem
sul tuo player.
Ecco un 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 al player su null e rilascia le risorse del player.
- Rilascia lo stato del
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 la versione 24 e successive dell'SDK Android:
Per supportare le versioni dell'SDK per Android precedenti alla 24:
- onResume()
- onPause()
onStart()
e onResume()
mappano a playerView.onResume()
, mentre onStop()
e
onPause()
mappano a playerView.onPause()
.
Questo passaggio utilizza anche l'evento
onSaveInstanceState()
per tentare di salvare il 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()); } } ... }
(Facoltativo) Configurazione dello stream VOD
Se la tua app deve riprodurre contenuti VOD con annunci, devi svolgere quanto segue:
- 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. Ora stai richiedendo e riproducendo uno stream multimediale con l'estensione ExoPlayer IMA. Dai un'occhiata agli esempi di DAI per Android su GitHub per il codice completo.