Erste Schritte mit der ExoPlayer IMA-Erweiterung

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

Dies sind einige der Vorteile der Erweiterung:

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

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

Streamunterstützung für ExoPlayer-IMA-Erweiterungen
	Livestream	VOD-Streams
HLS
DASH

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

Dieser Leitfaden basiert auf dem ExoPlayer-Leitfaden und zeigt, wie Sie eine vollständige Anwendung erstellen und die Erweiterung integrieren. Ein Beispiel mit einer vollständigen Beispielanwendung finden Sie unter ExoPlayerExample von GitHub.

Wichtiger Hinweis: Die ExoPlayer-IMA-Erweiterung hängt vom ExoPlayer ab. Wenn Sie einen anderen Player verwenden möchten, folgen Sie dem Startleitfaden, um das IMA DAI SDK in Ihre App einzubinden.

Voraussetzungen

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

Ein neues Android Studio-Projekt erstellen

So erstellen Sie ein Android Studio-Projekt:

• Starte Android Studio.
• Wählen Sie Start a new Android Studio Project (Neues Android Studio-Projekt starten) aus.
• Wählen Sie auf der Seite Projekt auswählen die Vorlage No Activity (Keine Aktivität) aus.
• Klicke auf Weiter.

• Benennen Sie Ihr Projekt auf der Seite Projekt konfigurieren und wählen Sie als Sprache Java 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 zum Projekt hinzufügen

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

Konfigurieren Sie Ihre Anwendung und aktivieren Sie multidex. Das ist aufgrund der Größe der Erweiterung erforderlich und bei Apps erforderlich, in 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 19
      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 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 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 aktuelle Version des IMA SDK eine ausdrückliche Absichtserklärung zum Öffnen von Weblinks erforderlich. Fügen Sie der Manifestdatei Ihrer App das folgende Snippet hinzu, um Klicks auf Anzeigen zu ermöglichen (Nutzer klicken auf die Schaltfläche Weitere Informationen).

Hinweis :Künftige Versionen des IMA SDK enthalten diese Angaben automatisch und werden mit der Manifestdatei Ihrer App 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 mit Beispielstream-Assets für das IMA-Beispiel finden Sie Beispiele für Stream-Assets, mit denen Sie Ihr Projekt testen können. Informationen zum Einrichten eigener Streams finden Sie im Ad Manager-Abschnitt zur dynamischen Anzeigenbereitstellung.

In diesem Schritt wird die Einrichtung eines Livestreams veranschaulicht. Die ExoPlayer IMA-Erweiterung unterstützt aber auch VOD-Streams für die dynamische Anzeigenbereitstellung. Im Schritt für Video-on-Demand-Streams (VOD) erfährst du, welche Änderungen deine App zur 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üge den Asset-Schlüssel des HLS-Streams Big Buck Bunny (Live) hinzu, um ihn mit diesem Stream zu testen. Auf der Beispiel-Stream-Seite von IMA sind weitere Streams zum Testen verfügbar.

Erstellen Sie eine KEY_ADS_LOADER_STATE-Konstante, um den Status AdsLoader 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 die PlayerView zu finden und nach einem gespeicherten AdsLoader.State zu suchen, der beim Initiieren des adsLoader-Objekts verwendet werden kann.

Aktivieren Sie außerdem Multidex, wenn dies aufgrund der Methodenanzahl und minSdkVersion Ihrer Anwendung erforderlich ist (wie in Schritt 2 erläutert).

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.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Methoden zum Initialisieren des Players hinzufügen

Füge eine Methode zur Initialisierung des Players hinzu und führe die folgenden Schritte aus:

• Erstellen Sie eine AdsLoader-Instanz.
• Erstellen Sie ExoPlayer.
• Erstelle eine MediaItem mit dem Asset-Schlüssel des Livestreams.
• Lege für MediaItem deinen Player fest.

Hinweis:In diesem Abschnitt werden Methoden mit Namen verwendet, die sich auf Konzepte der serverseitigen Anzeigenbereitstellung (SSAI) beziehen.

• Die dynamische Anzeigenbereitstellung in Google Ad Manager ist eine Instanz der serverseitigen Anzeigenbereitstellung.
• Die Implementierung der ExoPlayer-IMA-Erweiterung in diesem Leitfaden wurde speziell für die dynamische Anzeigenbereitstellung in Ad Manager entwickelt. Die ExoPlayer-IMA-Erweiterungen unterstützen auch andere SSAI-Instanzen wie die Google Cloud Platform, die in dieser Anleitung 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 Loslassen des Players hinzufügen

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

• Setze die Spielerreferenzen 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();
  }

Spielerereignisse verarbeiten

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

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

• onStart()
• onStop()

Zur Unterstützung von Android SDK-Versionen unter 24: – onResume() – onPause()

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

Wichtiger Hinweis :In diesem Beispiel sollen sowohl die Android SDK-Version 24 als auch die Versionen vor 24 unterstützt werden. Verwende onStart()/onStop(), wenn das Android SDK Version 24 oder höher unterstützt wird, und onResume()/onPause(), wenn Versionen unter 24 unterstützt werden.

In diesem Schritt wird auch das Ereignis onSaveInstanceState() verwendet, um das 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 in Ihrer App VOD-Inhalte mit Anzeigen wiedergegeben werden müssen, gehen Sie so vor:

1. Füge CMS ID und Video ID für einen VOD-Teststream hinzu.
2. Erstellen Sie mit ImaServerSideAdInsertionUriBuilder() einen SSAI-VOD-URI.
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 = "2528370";
  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 spielen ihn ab. Den vollständigen Code finden Sie in den Beispielen für die dynamische Anzeigenbereitstellung in Android auf GitHub.