Inizia a utilizzare l'estensione IMA ExoPlayer

ExoPlayer è un media player a livello di applicazione per Android. Questa guida illustra come utilizzare Estensione IMA di ExoPlayer, che aggrega l'SDK IMA DAI, per richiedere e riprodurre uno stream multimediale con sia gli annunci che i 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 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 sull'ExoPlayer guida e mostra come creare un'app completa e integrare l'estensione. Consulta ExoPlayerExample su GitHub per un esempio con un'app di esempio completa.

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

Prerequisiti

• Android Studio
• AndroidX Media3 ExoPlayer versione 1.0.0 o successive per il supporto di 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 progetto, assegna un nome al progetto e seleziona Java come lingua.

  Nota: l'SDK IMA DAI è compatibile con Kotlin. Tuttavia, l'esempio trattato in questa guida utilizza Java.

• Fai clic su Fine.

Aggiungere l'estensione ExoPlayer IMA al progetto

Aggiungi 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 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 di clic sugli annunci (utenti che fanno clic sul pulsante Scopri di più).

Nota: le versioni future dell'SDK IMA DAI includeranno automaticamente questi dichiarazioni e verrà unita al file manifest della tua richiesta.

  <?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 una LinearLayout, consigliata 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 per i video on demand (VOD) streaming le modifiche necessarie alla 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 il PlayerView e cercare un metodo salvato AdsLoader.State, che può essere utilizzato quando viene avviato l'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 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.

Nota: questa sezione utilizza metodi i cui nomi fanno riferimento all'annuncio lato server di inserimento (SSAI).

• Il DAI di Google Ad Manager è un'istanza di SSAI.
• L'implementazione dell'estensione IMA di ExoPlayer in questa guida è progettata per funzionare specificamente con DAI di Ad Manager. Le estensioni IMA di ExoPlayer supportano anche altre istanze SSAI, come la piattaforma Google Cloud, che non sono mostrate in questa guida.

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 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 la versione 24 e successive dell'SDK Android:

• onStart()
• onStop()

Per supportare le versioni dell'SDK Android precedenti alla 24: - onResume() - onPause()

onStart() e onResume() mappano a playerView.onResume(), mentre onStop() e onPause() mappano a playerView.onPause().

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

Questo passaggio utilizza anche 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 deve riprodurre contenuti VOD con annunci, devi svolgere quanto segue:

1. Aggiungi CMS ID e Video ID per uno stream di prova VOD.
2. Crea un URI VOD SSAI utilizzando ImaServerSideAdInsertionUriBuilder().
3. 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 ExoPlayer estensione IMA. Dai un'occhiata agli esempi di DAI per Android su GitHub per il codice completo.