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 beliebigen <ph type="x-smartling-placeholder"></ph> VAST-kompatiblen Ad-Server bereitstellen und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit clientseitigen IMA SDKs Sie behalten die Kontrolle über die Videowiedergabe, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separater Videoplayer, der sich über dem Videoplayer der App befindet.

In diesem Leitfaden wird gezeigt, wie Sie das IMA SDK mithilfe der Methode IMA-Erweiterung ExoPlayer: Wenn Sie sich eine fertige Beispielintegration ansehen oder an der Lösung teilnehmen möchten, laden Sie die BasicExample von GitHub.

Clientseitiges IMA – Übersicht

Für die clientseitige Implementierung von IMA sind vier SDK-Hauptkomponenten erforderlich, die in diesem Leitfaden:

  • AdDisplayContainer: Ein Containerobjekt, in dem Anzeigen gerendert werden.
  • AdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur ein Anzeigenladeprogramm instanziieren, das während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. In den Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie Anzeigenabmessungen.
  • AdsManager: Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf die Anzeige wartet Ereignisse, die vom SDK ausgelöst werden.

Vorbereitung

Bevor Sie beginnen, müssen Sie Android Studio 3.0 oder höher

1. Ein neues Android Studio-Projekt erstellen

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

  1. Starte Android Studio.
  2. Wählen Sie Start a new Android Studio project aus.
  3. Wähle 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 Ihr 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 Abhängigkeiten. Aufgrund der Größe der ExoPlayer IMA-Erweiterung implementieren und aktivieren Sie Hier ist Multidex. Dies ist bei Apps erforderlich, bei denen minSdkVersion auf 20 oder niedriger festgelegt ist. Fügen Sie außerdem einen neuen compileOptions hinzu, um die Informationen zur Java-Versionskompatibilität 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 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 deine App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, werden die aktuelle und die neueste Version der Für das IMA SDK ist eine explizite Absichtserklärung zum Öffnen von Weblinks erforderlich. Fügen Sie das folgende Snippet die Manifestdatei Ihrer App, um Anzeigenklicks zu ermöglichen (Nutzer, die auf die Seite "Weitere Informationen" Schaltfläche). <ph type="x-smartling-placeholder"> 
  <?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. UI-Container für Anzeigen erstellen

Erstelle die Ansicht, die als ExoPlayer-PlayerView verwendet werden soll, indem du ein StyledPlayerView erstellst. -Objekt mit geeigneter ID. Auch die androidx.constraintlayout.widget.ConstraintLayout zu 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. Content-URL und Anzeigen-Tag-URL für die Anzeigenanfrage hinzufügen

Fügen Sie strings.xml Einträge hinzu, um die 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 MainActivity-Klasse, um Activity durch Hinzufügen privater Variablen für PlayerView, SimpleExoPlayer und ImaAdsLoader.

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 Methode onCreate und fügen Sie die erforderlichen Variablenzuweisungen hinzu, um ein Neues adsLoader-Objekt mit der Anzeigen-Tag-URL

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 Loslassen des Players hinzu. In der Initialisierung die SimpleExoPlayer. Erstellen Sie dann den AdsMediaSource. und stelle ihn auf 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. Player-Ereignisse verarbeiten

Erstellen Sie schließlich Callbacks für die Lebenszyklus-Ereignisse 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.
      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();
  }

  ...

}

Fertig! Sie fordern jetzt Anzeigen mit dem IMA SDK an und schalten diese ein. Weitere Informationen finden Sie in den anderen Leitfäden oder in den Beispiele auf GitHub