Wenn Sie sich mit anderen Nutzern über unsere Produkte austauschen und Feedback geben möchten, treten Sie dem offiziellen Ad Manager-Discord-Kanal auf dem Server der Google Advertising and Measurement Community bei.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Mit Full-Service-DAI einrichten

Plattform auswählen: HTML5 Android iOS tvOS Cast Roku

In diesem Leitfaden wird gezeigt, wie Sie das IMA DAI SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich eine fertige Beispielintegration ansehen oder nachvollziehen möchten, laden Sie das BasicExample von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung von IMA DAI umfasst vier Hauptkomponenten des SDK, die in diesem Leitfaden beschrieben werden:

StreamDisplayContainer: Ein Containerobjekt, das sich über dem Videowiedergabeelement befindet und die UI-Elemente der Anzeige enthält.
AdsLoader: Ein Objekt, das Streams anfordert und Ereignisse verarbeitet, die durch Antwortobjekte auf Streamanfragen ausgelöst werden. Sie sollten nur einen Anzeigen-Loader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
StreamRequest: Ein Objekt, das eine Streamanfrage definiert. Streamanfragen können entweder für Video-on-Demand- oder Livestreams gestellt werden. Bei Livestream-Anfragen wird ein Asset-Schlüssel angegeben, bei VOD-Anfragen eine CMS-ID und eine Video-ID. Beide Anfragetypen können optional einen API-Schlüssel enthalten, der für den Zugriff auf bestimmte Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigenkennungen gemäß den Google Ad Manager-Einstellungen verarbeiten kann.
StreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem Backend für die dynamische Anzeigenbereitstellung verarbeitet. Der Stream-Manager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Vorbereitung

Android Studio
Beispiel-Videoplayer-App für die SDK-Integration

Beispiel-Videoplayer-App herunterladen und ausführen

Die Beispiel-App enthält einen funktionierenden Videoplayer, der HLS-Videos wiedergibt. Verwenden Sie dies als Ausgangspunkt für die Integration der DAI-Funktionen des IMA DAI SDK.

Laden Sie die Beispiel-Videoplayer-App herunter und extrahieren Sie sie.
Starten Sie Android Studio und wählen Sie Open an existing Android Studio project aus. Wenn Android Studio bereits ausgeführt wird, wählen Sie File > New > Import Project aus. Wählen Sie dann SampleVideoPlayer/build.gradle aus.
Führen Sie eine Gradle-Synchronisierung aus, indem Sie Tools > Android > Sync Project with Gradle Files auswählen.
Prüfen Sie, ob die Player-App auf einem physischen Android-Gerät oder einem virtuellen Android-Gerät kompiliert und ausgeführt wird. Verwenden Sie dazu Ausführen > „App“ ausführen. Es ist normal, dass es einen Moment dauert, bis der Videostream geladen ist und abgespielt wird.

Beispiel-Videoplayer ansehen

Der Beispiel-Videoplayer enthält noch keinen Integrationscode für das IMA SDK für die dynamische Anzeigenbereitstellung. Die Beispiel-App besteht aus zwei Hauptteilen:

samplevideoplayer/SampleVideoPlayer.java: Ein ExoPlayer-basierter HLS-Player, der als Grundlage für die IMA-DAI-Integration dient.
videoplayerapp/MyActivity.java: Diese Aktivität erstellt den Videoplayer und übergibt ihm eine Context und eine media3.ui.PlayerView.

IMA DAI SDK zur Player-App hinzufügen

Außerdem müssen Sie einen Verweis auf das IMA DAI SDK einfügen. Fügen Sie in Android Studio der Datei build.gradle auf Anwendungsebene (unter app/build.gradle) Folgendes hinzu: Für das IMA SDK muss die Entzuckerung der Bibliothek aktiviert sein. Dazu müssen Sie coreLibraryDesugaringEnabled true festlegen und 'com.android.tools:desugar_jdk_libs' als Abhängigkeit in der Datei build.gradle hinzufügen. Weitere Informationen finden Sie unter Java 11+-APIs, die durch Entzuckerung mit der nio-Spezifikation verfügbar sind.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
    implementation("androidx.appcompat:appcompat:1.8.0")
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")
    implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
    implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
    implementation("androidx.mediarouter:mediarouter:1.8.1")
    implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.40.0")
}build.gradle

IMA DAI SDK einbinden

Erstellen Sie im Paket videoplayerapp (in app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) eine neue Klasse mit dem Namen SampleAdsWrapper, um die vorhandene SampleVideoPlayer zu umschließen und Logik zur Implementierung von IMA DAI hinzuzufügen. Dazu müssen Sie zuerst ein AdsLoader-Objekt erstellen, mit dem der DAI-Stream angefordert wird.

Dieses Snippet enthält Beispielparameter für HLS- und DASH- sowie Live- und VOD-Streams. Aktualisieren Sie die Variable CONTENT_TYPE, um festzulegen, welcher Stream abgespielt wird.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.content.Context;
import android.view.ViewGroup;
import android.webkit.WebView;
import androidx.annotation.Nullable;
import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
import com.google.ads.interactivemedia.v3.api.CuePoint;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
import com.google.ads.interactivemedia.v3.api.StreamManager;
import com.google.ads.interactivemedia.v3.api.StreamRequest;
import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

/** This class adds ad-serving support to Sample HlsVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Live HLS stream asset key.
  private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  // Live DASH stream asset key.
  private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";

  // VOD HLS content source and video IDs.
  private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
  private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";

  // VOD DASH content source and video IDs.
  private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
  private static final String TEST_DASH_VIDEO_ID = "tos-dash";

  private static final String NETWORK_CODE = "21775744923";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  private enum ContentType {
    LIVE_HLS,
    LIVE_DASH,
    VOD_HLS,
    VOD_DASH,
  }

  // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
  private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {
    void log(String logMessage);
  }

  private final ImaSdkFactory sdkFactory;
  private AdsLoader adsLoader;
  private StreamManager streamManager;
  private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;

  private final SampleVideoPlayer videoPlayer;
  private final Context context;
  private final ViewGroup adUiContainer;

  private String fallbackUrl;
  private Logger logger;

  /**
   * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
   *
   * @param context the app's context.
   * @param videoPlayer underlying HLS video player.
   * @param adUiContainer ViewGroup in which to display the ad's UI.
   */
  public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
    this.videoPlayer = videoPlayer;
    this.context = context;
    this.adUiContainer = adUiContainer;
    sdkFactory = ImaSdkFactory.getInstance();
    playerCallbacks = new ArrayList<>();
    createAdsLoader();
  }

  private void enableWebViewDebugging() {
    WebView.setWebContentsDebuggingEnabled(true);
  }

  private void createAdsLoader() {
    enableWebViewDebugging();
    VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
    StreamDisplayContainer displayContainer =
        ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
    videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
    adsLoader =
        sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
  }

  public void requestAndPlayAds() {
    adsLoader.addAdErrorListener(this);
    adsLoader.addAdsLoadedListener(this);
    adsLoader.requestStream(buildStreamRequest());
  }
SampleAdsWrapper.java

Erstellen Sie eine createSampleVideoPlayerCallback()-Hilfsmethode, um eine SampleVideoPlayerCallback-Schnittstelleninstanz zu erstellen, die VideoStreamPlayer.VideoStreamPlayerCallback erweitert.

Damit die dynamische Anzeigenbereitstellung funktioniert, muss der Player ID3-Ereignisse an das IMA DAI SDK übergeben. Im folgenden Beispielcode wird dies mit der Methode callback.onUserTextReceived() erreicht.

private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
  return new SampleVideoPlayerCallback() {
    @Override
    public void onUserTextReceived(String userText) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onUserTextReceived(userText);
      }
    }

    @Override
    public void onSeek(int windowIndex, long positionMs) {
      // See if we would seek past an ad, and if so, jump back to it.
      long newSeekPositionMs = positionMs;
      if (streamManager != null) {
        CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
        if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
          newSeekPositionMs = prevCuePoint.getStartTimeMs();
        }
      }
      videoPlayer.seekTo(windowIndex, newSeekPositionMs);
    }

    @Override
    public void onContentComplete() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onContentComplete();
      }
    }

    @Override
    public void onPause() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onPause();
      }
    }

    @Override
    public void onResume() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onResume();
      }
    }

    @Override
    public void onVolumeChanged(int percentage) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onVolumeChanged(percentage);
      }
    }
  };
}
SampleAdsWrapper.java

Fügen Sie eine buildStreamRequest()-Methode hinzu, um die SteamRequest zu erstellen. Bei dieser Methode wird je nach Einstellung der Variable CONTENT_TYPE zwischen verschiedenen Streams gewechselt. Der in diesem Leitfaden verwendete Standardstream ist der VOD-HLS-Beispielstream von IMA.

@Nullable
private StreamRequest buildStreamRequest() {
  StreamRequest request;
  switch (CONTENT_TYPE) {
    case LIVE_HLS:
      // Live HLS stream request.
      return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
    case LIVE_DASH:
      // Live DASH stream request.
      return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
    case VOD_HLS:
      // VOD HLS request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.HLS);
      return request;
    case VOD_DASH:
      // VOD DASH request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.DASH);
      return request;
  }
  // Content type not selected.
  return null;
}
SampleAdsWrapper.java

Außerdem benötigen Sie einen VideoStreamPlayer, um den Stream abzuspielen. Fügen Sie daher eine createVideoStreamPlayer()-Methode hinzu, die eine anonyme Klasse erstellt, die VideoStreamPlayer implementiert.

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }

    @Override
    public void pause() {
      // Pause player.
      videoPlayer.pause();
    }

    @Override
    public void resume() {
      // Resume player.
      videoPlayer.play();
    }

    @Override
    public int getVolume() {
      // Make the video player play at the current device volume.
      return 100;
    }

    @Override
    public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.add(videoStreamPlayerCallback);
    }

    @Override
    public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.remove(videoStreamPlayerCallback);
    }

    @Override
    public void onAdBreakStarted() {
      // Disable player controls.
      videoPlayer.enableControls(false);
      log("Ad Break Started\n");
    }

    @Override
    public void onAdBreakEnded() {
      // Re-enable player controls.
      if (videoPlayer != null) {
        videoPlayer.enableControls(true);
      }
      log("Ad Break Ended\n");
    }

    @Override
    public void onAdPeriodStarted() {
      log("Ad Period Started\n");
    }

    @Override
    public void onAdPeriodEnded() {
      log("Ad Period Ended\n");
    }

    @Override
    public void seek(long timeMs) {
      // An ad was skipped. Skip to the content time.
      videoPlayer.seekTo(timeMs);
      log("seek");
    }

    @Override
    public VideoProgressUpdate getContentProgress() {
      return new VideoProgressUpdate(
          videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
    }
  };
}
SampleAdsWrapper.java

Implementieren Sie die erforderlichen Listener und fügen Sie Unterstützung für die Fehlerbehandlung hinzu.

Beachten Sie die AdErrorListener-Implementierung, da eine Fallback-URL aufgerufen wird, wenn die Anzeigen nicht wiedergegeben werden können. Da sich Content und Anzeigen in einem Stream befinden, müssen Sie darauf vorbereitet sein, einen Fallback-Stream aufzurufen, wenn im Stream für die dynamische Anzeigenbereitstellung ein Fehler auftritt.

/** AdErrorListener implementation */
@Override
public void onAdError(AdErrorEvent event) {
  log(String.format("Error: %s\n", event.getError().getMessage()));
  // play fallback URL.
  log("Playing fallback Url\n");
  videoPlayer.setStreamUrl(fallbackUrl);
  videoPlayer.enableControls(true);
  videoPlayer.play();
}

/** AdEventListener implementation */
@Override
public void onAdEvent(AdEvent event) {
  switch (event.getType()) {
    case AD_PROGRESS:
      // Do nothing or else log will be filled by these messages.
      break;
    default:
      log(String.format("Event: %s\n", event.getType()));
      break;
  }
}

/** AdsLoadedListener implementation */
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);
  streamManager.init();
}

/** Sets fallback URL in case ads stream fails. */
void setFallbackUrl(String url) {
  fallbackUrl = url;
}
SampleAdsWrapper.java

Fügen Sie Code für das Logging hinzu.

/** Sets logger for displaying events to screen. Optional. */
void setLogger(Logger logger) {
  this.logger = logger;
}

private void log(String message) {
  if (logger != null) {
    logger.log(message);
  }
}SampleAdsWrapper.java

Ändern Sie MyActivity in videoplayerapp, um SampleAdsWrapper zu instanziieren und aufzurufen. Rufen Sie hier auch ImaSdkFactory.initialize() auf und verwenden Sie eine Hilfsmethode, um eine ImaSdkSettings-Instanz zu erstellen.

Wichtig: Um die IMA-Ladezeiten zu verbessern, rufen Sie die Methode ImaSdkFactory.initialize() so früh wie möglich im App-Lebenszyklus auf. Wenn Sie die Methode frühzeitig aufrufen, hat IMA mehr Zeit, die erforderlichen Ressourcen vor der ersten Streamanfrage zu laden. Der Methodenaufruf ImaSdkFactory.initialize() akzeptiert eine ImaSdkSettings-Instanz. Achten Sie darauf, hier und beim Erstellen einer AdsLoader-Instanz dieselben Einstellungswerte zu verwenden. In diesem Beispiel wird die Hilfsmethode getImaSdkSettings() verwendet, um sicherzustellen, dass die Einstellungswerte identisch sind. Weitere Informationen finden Sie im Leitfaden zur Optimierung der IMA-Ladezeit.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.res.Configuration;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.ImageButton;
import android.widget.ScrollView;
import android.widget.TextView;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;

/** Main Activity that plays media using {@link SampleVideoPlayer}. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String DEFAULT_STREAM_URL =
      "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
  private static final String APP_LOG_TAG = "ImaDaiExample";
  private static final String PLAYER_TYPE = "DAISamplePlayer";
  private static ImaSdkSettings imaSdkSettings;

  protected SampleVideoPlayer sampleVideoPlayer;
  protected ImageButton playButton;

  private boolean contentHasStarted = false;

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

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

    View rootView = findViewById(R.id.videoLayout);
    sampleVideoPlayer =
        new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
    sampleVideoPlayer.enableControls(false);
    playButton = rootView.findViewById(R.id.playButton);
    final SampleAdsWrapper sampleAdsWrapper =
        new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
    sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);

    final ScrollView scrollView = findViewById(R.id.logScroll);
    final TextView textView = findViewById(R.id.logText);

    sampleAdsWrapper.setLogger(
        logMessage -> {
          Log.i(APP_LOG_TAG, logMessage);
          if (textView != null) {
            textView.append(logMessage);
          }
          if (scrollView != null) {
            scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
          }
        });

    // Set up play button listener to play video then hide play button.
    playButton.setOnClickListener(
        view -> {
          if (contentHasStarted) {
            sampleVideoPlayer.play();
          } else {
            contentHasStarted = true;
            sampleVideoPlayer.enableControls(true);
            sampleAdsWrapper.requestAndPlayAds();
          }
          playButton.setVisibility(View.GONE);
        });
    orientVideoDescription(getResources().getConfiguration().orientation);
  }
MyActivity.java

Fügen Sie die Hilfsmethode getImaSdkSettings() hinzu, um eine ImaSdkSettings-Instanz zu erstellen.

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

Ändern Sie die Layoutdatei activity_my.xml der Aktivität, um UI-Elemente für das Logging hinzuzufügen.

<!-- UI element for viewing SDK event log -->
<ScrollView
    android:id="@+id/logScroll"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    android:layout_weight="0.5"
    android:padding="5dp"
    android:background="#DDDDDD">

    <TextView
        android:id="@+id/logText"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">
    </TextView>
</ScrollView>activity_my.xml

Glückwunsch! Sie können jetzt Videoanzeigen in Ihrer Android-App anfordern und anzeigen lassen. Wenn Sie die Implementierung optimieren möchten, finden Sie weitere Informationen unter Lesezeichen, Snapback und in der API-Dokumentation.

Fehlerbehebung

Wenn bei der Wiedergabe einer Videoanzeige Probleme auftreten, lade das vollständige BasicExample herunter. Wenn es im BasicExample richtig funktioniert, liegt wahrscheinlich ein Problem mit dem IMA-Integrationscode Ihrer App vor.

Sollten weiterhin Probleme auftreten, besuchen Sie das IMA SDK-Forum.