Erste Schritte mit der Exoplayer IMA-Erweiterung

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server anfordern und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit den clientseitigen IMA-SDKs behalten Sie die Kontrolle über die Wiedergabe des Videocontents, während das SDK die Anzeigenwiedergabe übernimmt. Die Anzeigen werden in einem separaten Videoplayer über dem Videoplayer der App wiedergegeben.

In diesem Leitfaden wird gezeigt, wie das IMA SDK mit der IMA-Erweiterung ExoPlayer in ein leeres Android Studio-Projekt integriert wird. Wenn Sie sich eine abgeschlossene Beispielintegration ansehen oder ihr folgen möchten, laden Sie das BasicExample von GitHub herunter.

Clientseitiger IMA-Überblick

Die clientseitige Client-Implementierung umfasst vier SDK-Hauptkomponenten, die in diesem Leitfaden gezeigt werden:

  • AdDisplayContainer: Ein Containerobjekt, in dem Anzeigen gerendert werden.
  • AdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse von Anzeigenanfragen als Antwort verarbeitet. Sie sollten nur einen Anzeigenloader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. Bei 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 vom SDK ausgelöste Anzeigenereignisse überwacht.

Voraussetzungen

Bevor du beginnst, benötigst du 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 aus.
  3. Wählen Sie auf der Seite Projekt auswählen die Vorlage 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 zu Ihrem Projekt hinzufügen

Fügen Sie zuerst in der Datei build.gradle auf Anwendungsebene Importe für die Erweiterung zum Abschnitt für Abhängigkeiten hinzu. Aufgrund der Größe der ExoPlayer-IMA-Erweiterung können 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 ein neues compileOptions hinzu, um die Kompatibilitätsinformationen für die Java-Version anzugeben.

app/build.gradle
android {
    compileSdkVersion 30

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 16
      targetSdkVersion 30
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.appcompat:appcompat:1.3.1'
    implementation 'com.google.android.exoplayer:exoplayer-core:2.18.1'
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.18.1'
    implementation 'com.google.android.exoplayer:extension-ima:2.18.1'

    ...
}

Fügen Sie die vom IMA SDK zum Anfordern von Anzeigen erforderlichen Nutzerberechtigungen hinzu.

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>

3. Anzeigen-UI-Container erstellen

Erstelle die Ansicht, die als ExoPlayer-Player-Ansicht verwendet werden soll, indem du ein StyledPlayerView-Objekt mit einer entsprechenden ID erstellst. Ändern Sie außerdem androidx.constraintlayout.widget.ConstraintLayout in 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">

    <com.google.android.exoplayer2.ui.StyledPlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

4. Content-URL und Anzeigen-Tag-URL für die Anzeigenanfrage hinzufügen

Fügen Sie der Datei strings.xml Einträge hinzu, um Ihre Content-URL 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. Fügen Sie dazu private Variablen für PlayerView, SimpleExoPlayer und ImaAdsLoader hinzu.

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

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.multidex.MultiDex;
import com.google.android.exoplayer2.ExoPlayer;
import com.google.android.exoplayer2.MediaItem;
import com.google.android.exoplayer2.ext.ima.ImaAdsLoader;
import com.google.android.exoplayer2.source.DefaultMediaSourceFactory;
import com.google.android.exoplayer2.source.MediaSourceFactory;
import com.google.android.exoplayer2.ui.StyledPlayerView;
import com.google.android.exoplayer2.upstream.DataSource;
import com.google.android.exoplayer2.upstream.DefaultDataSourceFactory;
import com.google.android.exoplayer2.util.Util;

...

public class MainActivity extends Activity {

  private StyledPlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

}

6. adsLoader-Instanz erstellen

Überschreiben Sie die Methode onCreate 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 StyledPlayerView 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).build();
  }

}

7. Player initialisieren und freigeben

Füge Methoden zum Initialisieren und Loslassen des Players hinzu. Erstellen Sie in der Initialisierungsmethode SimpleExoPlayer. Erstelle dann AdsMediaSource und setze ihn auf den Player.

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

    MediaSourceFactory mediaSourceFactory =
        new DefaultMediaSourceFactory(dataSourceFactory)
                .setAdsLoaderProvider(unusedAdTagUri -> adsLoader)
                .setAdViewProvider(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

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

  • 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 with the ad tag url.
      adsLoader = new ImaAdsLoader(this, Uri.parse(getString(R.string.ad_tag_url)));
  }

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

  ...

}

Fertig! Mit dem IMA SDK werden jetzt Anzeigen angefordert und ausgeliefert. Informationen zu weiteren SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.