Wenn Sie sich mit anderen Nutzern über unsere Produkte austauschen und Feedback geben möchten, treten Sie dem offiziellen Ad Manager-Discord-Kanal auf dem Server der Google Advertising and Measurement Community bei.

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 Content anzufordern und abzuspielen.

Im Folgenden sind die Vorteile der Erweiterung aufgeführt:

Vereinfacht den Code, der zum Einbinden von IMA-Funktionen erforderlich ist.
Der Zeitaufwand für die Aktualisierung auf neue IMA-Versionen wird reduziert.

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

Unterstützung von Streams in der ExoPlayer-IMA-Erweiterung
	Livestream	VOD-Streams
HLS
DASH

ExoPlayer-IMA ab Version 1.1.0 unterstützt DASH-Livestreams.

In dieser Anleitung wird die ExoPlayer-Anleitung verwendet, um eine vollständige App zu erstellen und die Erweiterung zu integrieren. Eine vollständige Beispiel-App finden Sie unter ExoPlayerExample auf GitHub.

Vorbereitung

Android Studio
AndroidX Media3 ExoPlayer-Version 1.0.0 oder höher für die DAI-Unterstützung.

Ein neues Android Studio-Projekt erstellen

So erstellen Sie Ihr Android Studio-Projekt:

Starte Android Studio.
Wählen Sie Start a new Android Studio project aus.
Wählen Sie auf der Seite Projekt auswählen die Vorlage Keine Aktivität aus.
Klicken Sie auf Weiter.
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 Fertig.

ExoPlayer IMA-Erweiterung in Ihr Projekt einbinden

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

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

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

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"/>AndroidManifest.xml

ExoPlayer-UI einrichten

So richten Sie die ExoPlayer-Benutzeroberfläche ein:

Erstellen Sie das PlayerView-Objekt für ExoPlayer.

Ändern Sie die Ansicht androidx.constraintlayout.widget.ConstraintLayout in eine Ansicht LinearLayout, 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>
activity_my.xml

Streamparameter hinzufügen

Auf der Seite mit IMA-Beispielstreams finden Sie Beispielstream-Assets zum Testen Ihres Projekts. Informationen zum Einrichten eigener Streams finden Sie im Ad Manager-Abschnitt zur dynamischen Anzeigenbereitstellung.

In diesem Schritt wird ein Livestream eingerichtet. Die ExoPlayer IMA-Erweiterung unterstützt auch DAI-VOD-Streams. Informationen zu den Änderungen, die für VOD-Streams in deiner App erforderlich sind, findest du in diesem Schritt.

ExoPlayer IMA-Erweiterung importieren

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;
MyActivity.java

Fügen Sie in MyActivity.java die folgenden privaten Variablen hinzu:
Wenn Sie den HLS-Stream Big Buck Bunny (Live) testen möchten, fügen Sie den entsprechenden Asset-Schlüssel hinzu. Weitere Streams zum Testen finden Sie auf der Seite mit Beispielstreams für IMA.

Erstellen Sie eine KEY_ADS_LOADER_STATE-Konstante, um den AdsLoader-Zustand 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;
MyActivity.java

`adsLoader`-Instanz erstellen

Überschreiben Sie die Methode onCreate. Suchen Sie darin nach PlayerView und prüfen Sie, ob eine AdsLoader.State gespeichert 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;
}
MyActivity.java

Wichtig:Um die Ladezeiten von IMA zu verbessern, rufen Sie die Methode ImaSdkFactory.initialize() so früh wie möglich im App-Lebenszyklus auf. Wenn Sie die Methode frühzeitig aufrufen, hat IMA mehr Zeit, die erforderlichen Ressourcen vor der ersten Streamanfrage zu laden. Der ImaSdkFactory.initialize()-Methodenaufruf akzeptiert eine ImaSdkSettings-Instanz. Achten Sie darauf, dass Sie hier und beim Erstellen einer AdsLoader-Instanz dieselben Einstellungen verwenden. In diesem Beispiel wird die Hilfsmethode getImaSdkSettings() verwendet, um sicherzustellen, dass die Einstellungen gleich sind. Weitere Informationen finden Sie im Leitfaden zur Optimierung der IMA-Ladezeit.

Methoden zum Initialisieren des Players hinzufügen

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

Erstellen Sie eine AdsLoader-Instanz.
Erstellen Sie ExoPlayer.
Erstelle eine MediaItem mit dem Assetschlüssel des Livestreams.
Legen Sie die MediaItem für Ihren Player fest.

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

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:

Setzen Sie die Player-Referenzen auf „null“ und geben Sie die Ressourcen des Players frei.
Lassen Sie den adsLoader-Zustand los.

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

Spielerereignisse 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-Ebenen vor 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 Ereignis onSaveInstanceState() 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());
  }
}
MyActivity.java

VOD-Stream einrichten (optional)

Wenn in Ihrer App VOD-Inhalte mit Anzeigen wiedergegeben werden müssen, gehen Sie so vor:

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

So erstellen Sie einen SSAI-VOD-URI mit der Methode 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

Legen Sie die neue VOD-Stream-URI als Media-Item des Players mit der Methode MediaItem.fromUri() fest.

Wenn die Einrichtung erfolgreich war, können Sie einen Media-Stream mit der ExoPlayer IMA-Erweiterung anfordern und abspielen. Das vollständige Beispiel finden Sie unter Android DAI samples on GitHub.