Erste Schritte mit der ExoPlayer IMA-Erweiterung

ExoPlayer ist ein Mediaplayer für Android auf Anwendungsebene. In diesem Leitfaden erfahren Sie, wie Sie mit der ExoPlayer IMA-Erweiterung, die das IMA DAI SDK umschließt, einen Mediastream mit Anzeigen und Content anfordern und abspielen.

Die Erweiterung bietet unter anderem folgende Vorteile:

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

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

Unterstützung für ExoPlayer-IMA-Erweiterungsstreams
	Livestream	VOD-Streams
HLS
DASH

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

Diese Anleitung basiert auf dem ExoPlayer-Leitfaden und zeigt, wie eine vollständige Anwendung erstellt und die Erweiterung integriert wird. Ein Beispiel mit einer vollständigen Beispielanwendung finden Sie in der ExoPlayerExample auf GitHub.

Wichtiger Hinweis :Die IMA-Erweiterung von ExoPlayer hängt vom ExoPlayer ab. Falls Sie einen anderen Player verwenden möchten, folgen Sie der Anleitung im Startleitfaden, um das IMA DAI SDK in Ihre App zu integrieren.

Voraussetzungen

• Android Studio
• AndroidX Media3 ExoPlayer Version 1.0.0 oder höher für die Unterstützung der dynamischen Anzeigenbereitstellung

Ein neues Android Studio-Projekt erstellen

Führen Sie die folgenden Schritte aus, um Ihr Android Studio-Projekt zu erstellen:

• Starte Android Studio.
• Wählen Sie Start a new Android Studio project aus.
• Wähle 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 ist mit Kotlin kompatibel. Im Beispiel in diesem Leitfaden wird jedoch Java verwendet.

• Klicken Sie auf Fertigstellen.

ExoPlayer-IMA-Erweiterung zu Ihrem Projekt hinzufügen

Fügen Sie im Abschnitt dependencies der Datei build.gradle auf Anwendungsebene Importe für die Erweiterung hinzu.

Konfigurieren Sie Ihre App und aktivieren Sie Multidex. Das ist aufgrund der Größe der Erweiterung erforderlich und bei Apps erforderlich, bei denen minSdkVersion auf Android 4.4W (API-Level 20) oder niedriger festgelegt ist.

Beispiel:

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

Fügen Sie die Nutzerberechtigungen hinzu, die vom IMA DAI SDK zum Anfordern von Anzeigen benötigt werden:

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>

Intent-Deklarationen hinzufügen

Wenn Ihre App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, ist für die aktuelle und die aktuelle Version des IMA DAI SDK eine explizite Absichtserklärung zum Öffnen von Weblinks erforderlich. Fügen Sie der Manifestdatei Ihrer App das folgende Snippet hinzu, um Anzeigenklicks zu ermöglichen (Nutzer, die auf die Schaltfläche Weitere Informationen klicken).

Hinweis :Künftige Versionen des IMA DAI SDK enthalten diese Deklarierungen automatisch und werden mit der Manifestdatei Ihrer Anwendung zusammengeführt.

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

Benutzeroberfläche von ExoPlayer einrichten

Erstellen Sie das PlayerView-Objekt, das von ExoPlayer verwendet werden soll.

Ändern Sie androidx.constraintlayout.widget.ConstraintLayout in LinearLayout, was für die ExoPlayer IMA-Erweiterung empfohlen wird.

Beispiel:

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>

Streamparameter hinzufügen

Auf der Seite IMA-Beispielstream finden Sie Beispiele für Stream-Assets zum Testen Ihres Projekts. Im Abschnitt zur dynamischen Anzeigenbereitstellung in Ad Manager finden Sie Informationen zum Einrichten eigener Streams.

In diesem Schritt wird die Einrichtung eines Livestreams veranschaulicht. Die IMA-Erweiterung ExoPlayer unterstützt aber auch VOD-Streams für die dynamische Anzeigenbereitstellung. Im Schritt für VOD-Streams (Video-on-Demand) erfahren Sie, welche Änderungen Ihre Anwendung für die Verarbeitung von VOD-Streams benötigt.

ExoPlayer IMA-Erweiterung importieren

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

Fügen Sie MyActivity.java die folgenden privaten Variablen hinzu:

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

Fügen Sie den Assetschlüssel des HLS-Streams Big Buck Bunny (Live) hinzu, um ihn mit diesem Stream zu testen. Auf der Beispielstream-Seite von IMA sind weitere Streams zum Testen verfügbar.

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

Beispiel:

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;

}

adsLoader-Instanz erstellen

Überschreiben Sie die Methode onCreate, um den PlayerView zu finden, und suchen Sie nach einem gespeicherten AdsLoader.State, der beim Initiieren des adsLoader-Objekts verwendet werden kann.

Aktivieren Sie außerdem Multidex, wenn dies für die Methodenanzahl und minSdkVersion Ihrer App erforderlich ist (siehe Schritt 2).

Beispiel:

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

}

Methoden zum Initialisieren des Players hinzufügen

Füge eine Methode zum Initialisieren des Players hinzu und führe folgende Schritte aus:

• Erstellen Sie eine AdsLoader-Instanz.
• Erstellen Sie ExoPlayer.
• Erstelle eine MediaItem mit dem Assetschlüssel des Livestreams.
• Lege MediaItem auf deinen Player fest.

Hinweis:In diesem Abschnitt werden Methoden mit Namen verwendet, die auf Konzepte der serverseitigen Anzeigenbereitstellung (Server Side Ad Inserting, SSAI) verweisen.

• Die dynamische Anzeigenbereitstellung von Google Ad Manager ist eine Instanz der serverseitigen Anzeigenbereitstellung.
• Die Implementierung der IMA-Erweiterung „ExoPlayer“ in diesem Leitfaden wurde speziell für die dynamische Anzeigenbereitstellung in Ad Manager entwickelt. Die IMA-Erweiterungen von ExoPlayer unterstützen auch andere SSAI-Instanzen wie die Google Cloud Platform, die in diesem Leitfaden nicht behandelt werden.

Beispiel:

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

Methode zum Freigeben des Players hinzufügen

Füge eine Methode hinzu, um den Player in dieser Sequenz freizugeben:

• Setze die Spielerverweise auf null und gib die Ressourcen des Spielers frei.
• Geben Sie den Status von adsLoader frei.

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

Player-Ereignisse verarbeiten

Erstellen Sie schließlich Callbacks für die Lebenszyklusereignisse der Aktivität, um die Streamwiedergabe zu verarbeiten.

So unterstützen Sie Android SDK Version 24 oder höher:

• onStart()
• onStop()

So unterstützen Sie Android SDK-Versionen unter 24: – onResume() – onPause()

onStart() und onResume() werden playerView.onResume() und onStop() und onPause() playerView.onPause() zugeordnet.

Wichtiger Hinweis :In diesem Beispiel sollen sowohl Android SDK Version 24 oder höher als auch ältere Versionen unterstützt werden. Verwende onStart()/onStop() für die Unterstützung von Android SDK 24 oder höher und onResume()/onPause() für Versionen unter 24.

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

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

  ...

}

VOD-Stream einrichten (optional)

Wenn deine App VOD-Inhalte mit Anzeigen wiedergeben muss, gehe so vor:

1. Füge für einen VOD-Teststream CMS ID und Video ID hinzu.
2. Erstellen Sie mit ImaServerSideAdInsertionUriBuilder() einen VOD-URI für die serverseitige Anzeigenbereitstellung.
3. Verwende diesen neuen URI als Medienelement deines Players.

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

Fertig! Sie fordern jetzt einen Mediastream mit der ExoPlayer IMA-Erweiterung an und geben ihn wieder. Den vollständigen Code finden Sie in den Beispielen für die dynamische Anzeigenbereitstellung unter Android auf GitHub.