Erste Schritte mit der Exoplayer-IMA-Erweiterung

Mit IMA SDKs kannst du ganz einfach Multimedia-Anzeigen in deine 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 clientseitigen IMA SDKs behalten Sie die Kontrolle über die Videowiedergabe von Inhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer der App angezeigt wird.

In dieser Anleitung wird gezeigt, wie du das IMA SDK mithilfe der ExoPlayer IMA-Erweiterung in ein leeres Android Studio-Projekt einbindest. Wenn Sie sich eine fertige Beispielintegration ansehen oder nachvollziehen möchten, laden Sie BasicExample von GitHub herunter.

IMA-Client – Übersicht

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

  • AdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA UI-Elemente 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-Lademechanismus instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Objekt, das eine Anzeigenanfrage definiert. In Anzeigenanfragen werden die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie Anzeigendimensionen angegeben.
  • AdsManager: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf vom SDK ausgelöste Anzeigenereignisse wartet.

Vorbereitung

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

1. Ein neues Android Studio-Projekt erstellen

So erstellen Sie ein Android Studio-Projekt:

  1. Starte Android Studio.
  2. Wählen Sie Start a new Android Studio project (Neues Android Studio-Projekt starten) 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 das Projekt ein und wählen Sie „Java“ als Sprache aus.
  6. Klicken Sie auf Fertig.

2. ExoPlayer IMA-Erweiterung zum Projekt hinzufügen

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

app/build.gradle 
android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
      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.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.1'

    ...
}

Fügen Sie die Nutzerberechtigungen hinzu, die vom IMA SDK für das 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>

Absichtserklärungen hinzufügen

Wenn Ihre App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, erfordern die aktuelle und die letzten Versionen des IMA SDK eine ausdrückliche Erklärung, dass Sie Weblinks öffnen möchten. Fügen Sie der Manifestdatei Ihrer App das folgende Snippet hinzu, um Klicks auf Anzeigen zu aktivieren (Nutzer klicken auf die Schaltfläche Weitere Informationen). 
  <?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>

3. Container für die Anzeigen-UI erstellen

Erstelle die Ansicht, die als ExoPlayer-PlayerView verwendet werden soll, indem du ein StyledPlayerView-Objekt mit einer geeigneten ID erstellst. Ändern Sie auch die androidx.constraintlayout.widget.ConstraintLayout in eine LinearLayout.

app/src/main/res/layout/activity_main.xml 
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

4. Fügen Sie die Inhalts- und Anzeigen-Tag-URL für die Anzeigenanfrage hinzu.

Fügen Sie strings.xml Einträge hinzu, um die URL des Inhalts und die URL des VAST-Anzeigen-Tags zu speichern.

app/src/main/res/values/strings.xml 
<resources>
    <string name="app_name">Your_Project_Name</string>
    <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
    <string name="ad_tag_url"><![CDATA[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&impl=s&correlator=]]></string>

</resources>

5. ExoPlayer IMA-Erweiterung importieren

Fügen Sie die Importanweisungen für die ExoPlayer-Erweiterung hinzu. Aktualisieren Sie dann die Klasse MainActivity, um Activity zu erweitern, indem Sie private Variablen für PlayerView, SimpleExoPlayer und ImaAdsLoader hinzufügen.

app/src/main/java/com/example/project name/MainActivity.java 

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

}

6. adsLoader-Instanz erstellen

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

app/src/main/java/com/example/project name/MainActivity.java 
...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

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

    playerView = findViewById(R.id.player_view);

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

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

7. Player initialisieren und freigeben

Füge Methoden zum Initialisieren und Freigeben des Players hinzu. Erstellen Sie in der Methode „initialize“ die SimpleExoPlayer. Erstelle dann die AdsMediaSource und setze sie für den Player ein.

app/src/main/java/com/example/project name/MainActivity.java 
public class MainActivity extends Activity {

  ...

  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(getString(R.string.content_url));
    Uri adTagUri = Uri.parse(getString(R.string.ad_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);
  }
}

8. Spielerereignisse verarbeiten

Erstelle abschließend Callbacks für die Lebenszyklusereignisse des Spielers:

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
app/src/main/java/com/example/project name/MainActivity.java 
public class MainActivity extends Activity {

  private PlayerView playerView;
  private SimpleExoPlayer player;
  private ImaAdsLoader adsLoader;

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

      playerView = findViewById(R.id.player_view);

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

  @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
  protected void onDestroy() {
    super.onDestroy();
    adsLoader.release();
  }

  ...

}

Geschafft! Sie fordern jetzt Anzeigen über das IMA SDK an und schalten sie. Weitere Informationen zu den SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.