Erste Schritte mit der ExoPlayer IMA-Erweiterung

ExoPlayer ist ein Android Mediaplayer. In diesem Leitfaden erfahren Sie, wie Sie die ExoPlayer IMA-Erweiterung verwenden. Diese Erweiterung verwendet das IMA DAI SDK, um Media-Streams mit Anzeigen und Inhalten anzufordern und abzuspielen.

Im Folgenden sind die Vorteile der Erweiterung aufgeführt:

  • Vereinfacht den Code, der zum Einbinden von IMA-Funktionen erforderlich ist.
  • Verkürzt die Zeit, die für die Aktualisierung auf neue IMA-Versionen erforderlich ist.

Die ExoPlayer IMA-Erweiterung unterstützt die Streamingprotokolle HLS und DASH. Hier eine Zusammenfassung:

Streamunterstützung für die ExoPlayer IMA-Erweiterung
Livestream VOD-Streams
HLS Häkchen Häkchen
DASH Häkchen Häkchen

Die ExoPlayer IMA-Version 1.1.0 und höher unterstützt DASH-Livestreams.

In diesem Leitfaden wird der ExoPlayer-Leitfaden verwendet, um Ihnen beim Erstellen einer vollständigen App und beim Einbinden der Erweiterung zu helfen. Eine vollständige Beispiel App finden Sie unter ExoPlayerExample auf GitHub.

Vorbereitung

Ein neues Android Studio-Projekt erstellen

So erstellen Sie Ihr Android Studio-Projekt:

  1. Starte Android Studio.
  2. Wählen Sie Neues Android Studio-Projekt starten aus.
  3. Wählen Sie auf der Seite Projekt auswählen die Vorlage Keine Aktivität aus.
  4. Klicken Sie auf Weiter.
  5. Geben Sie auf der Seite Projekt konfigurieren einen Namen für Ihr Projekt ein und wählen Sie Java als Sprache aus. Hinweis: Das IMA DAI SDK funktioniert mit Kotlin, in diesem Leitfaden werden jedoch Java-Beispiele verwendet.
  • Klicken Sie auf Beenden.

Die ExoPlayer IMA-Erweiterung zu Ihrem Projekt hinzufügen

So fügen Sie die ExoPlayer IMA-Erweiterung hinzu:

  1. Fügen Sie die folgenden Importe in den Abschnitt dependencies der Datei build.gradle Ihrer App ein:

    dependencies {
    def media3_version = "1.9.1"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.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")
}

  2. Fügen Sie die Nutzerberechtigungen hinzu, die das IMA DAI SDK zum Anfordern von Anzeigen benötigt:

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

ExoPlayer-UI einrichten

So richten Sie die ExoPlayer-UI ein:

  1. Erstellen Sie das PlayerView-Objekt für ExoPlayer.

  2. Ändern Sie die Ansicht androidx.constraintlayout.widget.ConstraintLayout in eine LinearLayout-Ansicht, wie von der ExoPlayer IMA-Erweiterung empfohlen:

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

Streamparameter hinzufügen

Auf der IMA-Beispielstreamseite finden Sie Beispiel-Stream-Assets, mit denen Sie Ihr Projekt testen können. Informationen zum Einrichten eigener Streams finden Sie unter im Ad Manager-Abschnitt zur dynamischen Anzeigenbereitstellung.

In diesem Schritt wird ein Livestream eingerichtet. Die ExoPlayer IMA-Erweiterung unterstützt auch VOD-Streams für die dynamische Anzeigenbereitstellung. Informationen zu den Änderungen, die für VOD-Streams in Ihrer App erforderlich sind, finden Sie im Schritt für Video-on-Demand-Streams.

ExoPlayer IMA-Erweiterung importieren

  1. Fügen Sie die folgenden Importanweisungen für die ExoPlayer-Erweiterung hinzu:

    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;

  2. Fügen Sie in MyActivity.java diese privaten Variablen hinzu:

    Wenn Sie mit dem HLS-Stream Big Buck Bunny (Live) testen möchten, fügen Sie den zugehörigen Asset-Schlüssel hinzu. Weitere Streams zum Testen finden Sie auf der IMA-Beispielstreamseite.

  3. Erstellen Sie eine KEY_ADS_LOADER_STATE-Konstante, um den AdsLoader-Status zu speichern und abzurufen:

    /** 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;

Eine adsLoader-Instanz erstellen

Überschreiben Sie die Methode onCreate. Suchen Sie darin nach PlayerView und prüfen Sie, ob ein gespeicherter AdsLoader.State vorhanden ist. Sie können diesen Status verwenden, wenn Sie das adsLoader-Objekt initialisieren.

@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;
}

Methoden zum Initialisieren des Players hinzufügen

Fügen Sie eine Methode zum Initialisieren des Players hinzu. Diese Methode muss Folgendes tun:

  • Eine AdsLoader-Instanz erstellen
  • ExoPlayer erstellen
  • Mit dem Asset-Schlüssel des Livestreams ein MediaItem erstellen
  • MediaItem für den Player festlegen
// 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();
}

Methode zum Freigeben des Players hinzufügen

Fügen Sie eine Methode zum Freigeben des Players hinzu. Diese Methode muss die folgenden Aktionen in der angegebenen Reihenfolge ausführen:

  • Die Player-Referenzen auf null setzen und die Ressourcen des Players freigeben
  • Den adsLoader-Status freigeben
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();
}

Player-Ereignisse verarbeiten

Um Player-Ereignisse zu verarbeiten, erstellen Sie Callbacks für die Lebenszyklusereignisse der Aktivität, um die Streamwiedergabe zu verwalten.

Verwenden Sie für Android API-Level 24 und höher die folgenden Methoden:

Verwenden Sie für Android API-Level unter 24 die folgenden Methoden:

Die Methoden onStart() und onResume() werden playerView.onResume() zugeordnet, während onStop() und onPause() playerView.onPause() zugeordnet werden.

In diesem Schritt wird auch das onSaveInstanceState() Ereignis verwendet, um adsLoaderState zu speichern.

@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());
  }
}

VOD-Stream einrichten (optional)

Wenn Ihre App VOD-Inhalte mit Anzeigen abspielen muss, gehen Sie so vor:

  1. Fügen Sie eine CMS ID und eine Video ID für einen VOD-Stream hinzu. Verwenden Sie für Tests die folgenden Streamparameter:
    • CMS ID: "2548831"
    • Video ID: "tears-of-steel"

  2. Erstellen Sie mit der Methode ImaServerSideAdInsertionUriBuilder() einen SSAI-VOD-URI:

    /**
 * 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();
}

  3. Legen Sie den neuen VOD-Stream-URI mit der Methode MediaItem.fromUri() als Media-Item des Players fest:

Wenn alles funktioniert, können Sie mit der ExoPlayer IMA-Erweiterung einen Media-Stream anfordern und abspielen. Das vollständige Beispiel finden Sie unter Android DAI-Beispiele auf GitHub.