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 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 sull'ExoPlayer guida e mostra come creare un'app completa e integrare l'estensione. Consulta le ExoPlayerExample da GitHub, per vedere un esempio un'app di esempio completa.

Prerequisiti

• Android Studio
• AndroidX Media3 ExoPlayer versione 1.0.0 o successiva per DAI assistenza in tempo reale.

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 per la lingua.

• 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 l'app multidex. Si tratta di una operazione necessaria alle dimensioni dell'estensione ed è obbligatoria per le app per cui è impostato minSdkVersion ad Android 4.4W (livello API 20) o inferiore.

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>

Aggiungi dichiarazioni di intent

Se la tua app ha come target Android 11 (livello API 30) o versioni successive, i dati attuali e recenti delle versioni dell'SDK IMA DAI richiedono una dichiarazione di intenzione esplicita per aprire il sito 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ù).

  <?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.

Cambia androidx.constraintlayout.widget.ConstraintLayout in 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 dello stream

Guarda lo stream di esempio IMA pagina per lo stream di esempio per testare il progetto. Consulta anche la sezione di Ad Manager relativa DAI per informazioni sulla configurazione per i tuoi stream.

Questo passaggio illustra la configurazione di un live streaming, ma l'IMA di ExoPlayer supporta anche gli streaming DAI VOD. Consulta il passaggio per i video on demand (VOD) streaming per vedere 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 flusso di dati. Sono disponibili altri stream su cui testare Pagina stream di esempio dell'IMA.

Crea una costante KEY_ADS_LOADER_STATE per salvare e recuperare AdsLoader stato.

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.

Attiva inoltre il multidex se richiesto dal conteggio dei metodi della tua app e minSdkVersion (come spiegato in 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.

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 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 lo streaming per riprodurre un video.

Per supportare l'SDK Android 24 o versioni successive:

• onStart()
• onStop()

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

onStart() e onResume() sono mappati a playerView.onResume(), e onStop() e onPause() mappa con playerView.onPause().

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 è necessaria per riprodurre contenuti VOD con annunci, dovrai farlo le seguenti:

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 Android su GitHub per il codice completo.