Erste Schritte mit der Exoplayer-IMA-Erweiterung

Mit den IMA SDKs lassen sich Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit den clientseitigen IMA SDKs behalten Sie die Kontrolle über die Wiedergabe von Videoinhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer für die Inhalte der App positioniert ist.

In diesem Leitfaden wird gezeigt, wie Sie das IMA SDK in ein leeres Android Studio-Projekt einbinden. Dazu wird die ExoPlayer IMA-Erweiterung verwendet. Wenn Sie sich eine vollständige Beispielintegration ansehen oder sie nachvollziehen möchten, laden Sie BasicExample von GitHub herunter.

IMA-Clientseite – Übersicht

Die clientseitige Implementierung von IMA umfasst vier Haupt-SDK-Komponenten, die in diesem Leitfaden beschrieben werden:

  • AdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA Benutzeroberflächenelemente für Anzeigen rendert und die Sichtbarkeit misst, einschließlich Active View und Open Measurement.
  • AdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur einen Anzeigen-Loader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. In Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie die Anzeigengröße angegeben.
  • AdsManager: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf Anzeigenereignisse wartet, die vom SDK ausgelöst werden.

Vorbereitung

Bevor Sie beginnen, benötigen Sie Android Studio 3.0 oder höher.

1. Ein neues Android Studio-Projekt erstellen

So erstellen Sie Ihr Android Studio-Projekt:

  1. Starte Android Studio.
  2. Wählen Sie Start a new Android Studio project aus.
  3. Wählen Sie auf der Seite Choose your project (Projekt auswählen) die Vorlage Empty Activity (Leere 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.
  6. Klicken Sie auf Fertig.

2. ExoPlayer IMA-Erweiterung in Ihr Projekt einbinden

Fügen Sie zuerst in der build.gradle-Datei auf Anwendungsebene Importe für die Erweiterung in den Abschnitt „dependencies“ ein. Aufgrund der Größe der ExoPlayer IMA-Erweiterung müssen Sie hier Multidex implementieren und aktivieren. Dies ist für Apps erforderlich, bei denen minSdkVersion auf 20 oder niedriger festgelegt ist. Fügen Sie außerdem neue compileOptions hinzu, um die Informationen zur Kompatibilität mit der Java-Version anzugeben. 

apply plugin: 'com.android.application'

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdk 36

    // Java 17 required by Gradle 8+
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    defaultConfig {
        applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
        minSdkVersion 21
        targetSdkVersion 36
        multiDexEnabled true
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.8.0"
    implementation "androidx.media3:media3-ui:$media3_version"
    implementation "androidx.media3:media3-exoplayer:$media3_version"

    // The library adds the IMA ExoPlayer integration for ads.
    implementation "androidx.media3:media3-exoplayer-ima:$media3_version"

    implementation 'androidx.multidex:multidex:2.0.1'
}

build.gradle

3. Anzeigen-UI-Container erstellen

Erstellen Sie die Ansicht, die als ExoPlayer PlayerView verwendet werden soll, indem Sie ein androidx.media3.ui.PlayerView erstellen. Ändern Sie außerdem die androidx.constraintlayout.widget.ConstraintLayout in eine LinearLayout. 

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

4. ExoPlayer IMA-Erweiterung importieren

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

import static android.os.Build.VERSION.SDK_INT;

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.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;

MyActivity.java

Aktualisieren Sie dann die Klasse MainActivity, um Activity zu erweitern, indem Sie private Variablen für PlayerView, ExoPlayer, ImaAdsLoader und ImaSdkSettings hinzufügen: 

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String SAMPLE_VIDEO_URL =
      "https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
  private static final String SAMPLE_VAST_TAG_URL =
      "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
          + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90"
          + "&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator=";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;
  private ImaSdkSettings imaSdkSettings;

MyActivity.java

5. adsLoader-Instanz erstellen

Überschreiben Sie die onCreate-Methode und fügen Sie die erforderlichen Variablenzuweisungen hinzu, um ein neues adsLoader-Objekt mit der Ad-Tag-URL zu erstellen. 

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_my);
  MultiDex.install(this);

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

  // Create an AdsLoader.
  adsLoader =
      new ImaAdsLoader.Builder(/* context= */ this)
          .setAdEventListener(buildAdEventListener())
          .setImaSdkSettings(getImaSdkSettings())
          .build();
}

MyActivity.java

Erstellen Sie die Methode buildAdEventListener(), um ein AdEventListener-Objekt zurückzugeben, mit dem IMA-Ereignisse zur Fehlerbehebung protokolliert werden können. Die ExoPlayer IMA-Erweiterung verarbeitet IMA-Ereignisse bereits und benötigt hier keine zusätzlichen Informationen. 

public AdEvent.AdEventListener buildAdEventListener() {
  logText = findViewById(R.id.logText);
  logText.setMovementMethod(new ScrollingMovementMethod());

  return event -> {
    AdEvent.AdEventType eventType = event.getType();
    if (eventType == AdEvent.AdEventType.AD_PROGRESS) {
      return;
    }
    String log = "IMA event: " + eventType;
    if (logText != null) {
      logText.append(log + "\n");
    }
    Log.i(LOG_TAG, log);
  };
}

MyActivity.java

Erstellen Sie die Hilfsmethode getImaSdkSettings(), um ein ImaSdkSettings-Objekt zurückzugeben, mit dem Sie IMA SDK-Einstellungen festlegen können: 

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

6. Player initialisieren und freigeben

Fügen Sie Methoden hinzu, um den Player freizugeben und zu initialisieren. Erstellen Sie in der Methode initializePlayer() die ExoPlayer. Erstellen Sie dann AdsMediaSource und legen Sie es für den Player fest:

private void releasePlayer() {
  adsLoader.setPlayer(null);
  playerView.setPlayer(null);
  player.release();
  player = null;
}

private void initializePlayer() {
  // Set up the factory for media sources, passing the ads loader and ad view providers.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  MediaSource.Factory mediaSourceFactory =
      new DefaultMediaSourceFactory(dataSourceFactory)
          .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);

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

  // Create the MediaItem to play, specifying the content URI and ad tag URI.
  Uri contentUri = Uri.parse(SAMPLE_VIDEO_URL);
  Uri adTagUri = Uri.parse(SAMPLE_VAST_TAG_URL);
  MediaItem mediaItem =
      new MediaItem.Builder()
          .setUri(contentUri)
          .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
          .build();

  // Prepare the content and ad to be played with the SimpleExoPlayer.
  player.setMediaItem(mediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

MyActivity.java

7. Spielerereignisse verarbeiten

Erstellen Sie schließlich Callbacks für die Lebenszyklusereignisse des Players:

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
@Override
public void onStart() {
  super.onStart();
  if (SDK_INT > 23) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onResume() {
  super.onResume();
  if (SDK_INT <= 23 || player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
  if (SDK_INT <= 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onStop() {
  super.onStop();
  if (SDK_INT > 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
protected void onDestroy() {
  adsLoader.release();

  super.onDestroy();
}

MyActivity.java

Sie fordern jetzt erfolgreich Anzeigen mit dem IMA SDK an und präsentieren sie. Weitere Informationen zu erweiterten Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.