Inizia a utilizzare l'estensione IMA ExoPlayer

ExoPlayer è un media player per Android. Questa guida mostra come utilizzare l'estensione IMA di ExoPlayer. Questa estensione utilizza l'SDK IMA DAI per richiedere e riprodurre stream multimediali con annunci e contenuti.

Di seguito sono elencati i vantaggi dell'estensione:

• Semplifica il codice necessario per integrare le funzionalità IMA.
• Riduce il tempo necessario per l'aggiornamento alle nuove versioni dell'SDK IMA.

L'estensione IMA di ExoPlayer supporta i protocolli di streaming HLS e DASH. Ecco un riepilogo:

Supporto dello stream dell'estensione ExoPlayer-IMA
	Live streaming	Stream VOD
HLS
DASH

ExoPlayer-IMA versione 1.1.0 e successive supporta i live streaming DASH.

Questa guida utilizza la guida di ExoPlayer per aiutarti a creare un'app completa e integrare l'estensione. Per un'app di esempio completa, consulta ExoPlayerExample su GitHub.

Punto chiave: l'estensione ExoPlayer IMA richiede ExoPlayer. Se preferisci un altro player, segui la guida introduttiva per integrare l'SDK IMA DAI nella tua app.

Prerequisiti

• Android Studio
• AndroidX Media3 ExoPlayer versione 1.0.0 o successive per il supporto della DAI.

Crea un nuovo progetto Android Studio

Per creare il progetto Android Studio:

1. Avvia Android Studio.
2. Seleziona Avvia un nuovo progetto Android Studio.
3. Nella pagina Scegli il tuo progetto, seleziona il modello Nessuna attività.
4. Fai clic su Avanti.
5. Nella pagina Configura il progetto, assegna un nome al progetto e seleziona Java come linguaggio. Nota: l'SDK IMA DAI funziona con Kotlin, ma questa guida utilizza esempi Java.

• Fai clic su Fine.

Aggiungere l'estensione ExoPlayer IMA al progetto

Per aggiungere l'estensione ExoPlayer IMA:

1. Includi le seguenti importazioni nella sezione dependencies del file build.gradle dell'app:

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.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"
   }
   build.gradle
   

2. Aggiungi le autorizzazioni utente necessarie all'SDK IMA DAI per richiedere gli annunci:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

Configura l'interfaccia utente di ExoPlayer

Per configurare l'interfaccia utente di ExoPlayer:

1. Crea l'oggetto PlayerView per ExoPlayer.

2. Modifica la visualizzazione androidx.constraintlayout.widget.ConstraintLayout in una visualizzazione LinearLayout, come consigliato dall'estensione 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>
   activity_my.xml
   

Aggiungere i parametri dello stream

Consulta la pagina di esempio di stream IMA per gli asset di stream di esempio per testare il progetto. Per configurare i tuoi stream, consulta la sezione di Ad Manager su DAI.

Questo passaggio configura un live streaming. L'estensione IMA di ExoPlayer supporta anche gli stream VOD DAI. Per scoprire quali modifiche deve apportare la tua app per gli stream VOD, consulta il passaggio per gli stream video on demand (VOD).

Importa l'estensione ExoPlayer IMA

1. Aggiungi le seguenti istruzioni di importazione per l'estensione 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;
   MyActivity.java
   

2. In MyActivity.java, aggiungi queste variabili private:

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

   Per eseguire il test con lo stream HLS Big Buck Bunny (Live), aggiungi la relativa chiave asset. Puoi trovare altri stream da testare nella pagina di esempio di stream di IMA.

3. Crea una costante KEY_ADS_LOADER_STATE per salvare e recuperare lo stato di 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;
   MyActivity.java
   

Crea un'istanza adsLoader

Esegui l'override del metodo onCreate. All'interno, trova PlayerView e verifica la presenza di un AdsLoader.State salvato. Puoi utilizzare questo stato quando inizializzi l'oggetto 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;
}
MyActivity.java

Importante:per migliorare i tempi di caricamento di IMA, chiama il metodo ImaSdkFactory.initialize() il prima possibile nel ciclo di vita dell'app. La chiamata anticipata del metodo massimizza il tempo a disposizione di IMA per caricare le risorse necessarie prima della prima richiesta di stream. La chiamata al metodo ImaSdkFactory.initialize() accetta un'istanza ImaSdkSettings. Assicurati di utilizzare gli stessi valori delle impostazioni qui e quando crei un'istanza AdsLoader. Questo esempio utilizza il metodo helper getImaSdkSettings() per garantire che i valori delle impostazioni siano gli stessi. Per saperne di più, consulta la guida Ottimizzare il tempo di caricamento di IMA>.

Aggiungi metodi per inizializzare il player

Aggiungi un metodo per inizializzare il player. Questo metodo deve:

• Crea un'istanza AdsLoader.
• Crea il ExoPlayer.
• Crea un MediaItem utilizzando la chiave asset del live streaming.
• Imposta il MediaItem per il tuo giocatore.

// 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();
}
MyActivity.java

Nota: questa sezione utilizza metodi con nomi che fanno riferimento a concetti di inserimento di annunci lato server (SSAI).

• Google Ad Manager DAI è un esempio di SSAI.
• L'estensione ExoPlayer IMA di questa guida funziona in modo specifico con l'inserimento di annunci dinamici di Ad Manager. L'estensione ExoPlayer IMA supporta anche diverse soluzioni SSAI.

Aggiungere un metodo per rilasciare il giocatore

Aggiungi un metodo per rilasciare il giocatore. Questo metodo deve eseguire le seguenti azioni in sequenza:

• Imposta i riferimenti del player su null e rilascia le risorse del player.
• Rilascia lo stato 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();
}
MyActivity.java

Gestire gli eventi del giocatore

Per gestire gli eventi del player, crea callback per gli eventi del ciclo di vita dell'attività per gestire la riproduzione dello stream.

Per il livello API Android 24 e versioni successive, utilizza i seguenti metodi:

• onStart()
• onStop()

Per i livelli API Android precedenti a 24, utilizza i seguenti metodi:

• onResume()
• onPause()

I metodi onStart() e onResume() corrispondono a playerView.onResume(), mentre onStop() e onPause() corrispondono a playerView.onPause().

Punto chiave: questo esempio supporta la versione 24 e precedenti dell'SDK Android. Utilizza onStart()/onStop() per la versione 24 o successive dell'SDK Android e onResume()/onPause() per le versioni precedenti alla 24.

Questo passaggio utilizza anche l'evento onSaveInstanceState() per salvare 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());
  }
}
MyActivity.java

(Facoltativo) Configurazione dello stream VOD

Se la tua app deve riprodurre contenuti VOD con annunci, segui questi passaggi:

1. Aggiungi un CMS ID e un Video ID per uno stream VOD. Per i test, utilizza questi parametri dello stream:
   • ID CMS: "2548831"
   • ID video: "tears-of-steel"

2. Crea un URI VOD SSAI utilizzando il metodo 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();
   }
   MyActivity.java
   

3. Imposta il nuovo URI dello stream VOD come elemento multimediale del player utilizzando il metodo MediaItem.fromUri().

Se l'operazione va a buon fine, puoi richiedere e riprodurre un flusso multimediale con l'estensione ExoPlayer IMA. Per l'esempio completo, consulta Esempi di DAI per Android su GitHub.