IMA SDK für die dynamische Anzeigenbereitstellung einrichten

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 IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie das Umschalten zwischen Anzeigen- und Inhaltsvideo in Ihrer App nicht verwalten müssen.

Wählen Sie die DAI-Lösung aus, die Sie interessiert

Full-Service-DAI

In dieser Anleitung wird gezeigt, wie Sie das IMA DAI SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich eine vollständige Beispielintegration ansehen oder ihr folgen möchten, laden Sie BasicExample von GitHub herunter.

Übersicht über die IMA-DAI

Die Implementierung von IMA DAI umfasst vier Haupt-SDK-Komponenten, wie in diesem Leitfaden beschrieben:

• 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 für 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 erfolgen. In Livestream-Anfragen wird ein Asset-Schlüssel angegeben, in 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 die angegebenen Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigen-IDs 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 abspielt. Dies kann als Ausgangspunkt für die Integration der DAI-Funktionen des IMA DAI SDK dienen.

1. Laden Sie die Beispiel-App für den Videoplayer herunter und extrahieren Sie sie.

2. Starten Sie Android Studio und wählen Sie Open an existing Android Studio project (Vorhandenes Android Studio-Projekt öffnen) aus. Wenn Android Studio bereits ausgeführt wird, wählen Sie File > New > Import Project (Datei > Neu > Projekt importieren) aus. Wählen Sie dann SampleVideoPlayer/build.gradle aus.

3. Führen Sie eine Gradle-Synchronisierung aus, indem Sie Tools > Android > Sync Project with Gradle Files (Tools > Android > Projekt mit Gradle-Dateien synchronisieren) auswählen.

4. Achten Sie darauf, dass die Player-App auf einem physischen Android-Gerät oder einem virtuellen Android-Gerät kompiliert und ausgeführt wird. Verwenden Sie dazu Run > Run 'app' (Ausführen > „App“ ausführen). Es ist normal, dass es einige Momente dauert, bis der Videostream geladen ist und die Wiedergabe beginnt.

Beispielvideoplayer ansehen

Der Beispielvideoplayer enthält noch keinen Code für die IMA DAI SDK-Integration. Die Beispiel-App besteht aus zwei Hauptteilen:

1. samplevideoplayer/SampleVideoPlayer.java: Ein ExoPlayer-basierter HLS-Player, der als Grundlage für die IMA DAI-Integration dient.

2. videoplayerapp/MyActivity.java: Mit dieser Aktivität wird der Videoplayer erstellt und ein Context und ein media3.ui.PlayerView werden an ihn übergeben.

IMA DAI SDK zur Player-App hinzufügen

Sie müssen auch einen Verweis auf das IMA DAI SDK einfügen. Fügen Sie in Android Studio Folgendes in die build.gradle-Datei auf Anwendungsebene ein, die sich unter app/build.gradle befindet. Für das IMA SDK muss die Bibliothek „desugaring“ 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 Desugaring mit der NIO-Spezifikation verfügbar sind.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.9.1"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.0"))
    implementation("androidx.appcompat:appcompat:1.7.1")
    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.39.0")
}
build.gradle

IMA DAI SDK einbinden

1. 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 für die Implementierung von IMA DAI hinzuzufügen. Dazu müssen Sie zuerst ein AdsLoader erstellen, mit dem der DAI-Stream angefordert wird.

   Dieses Snippet enthält Beispielparameter für HLS- und DASH-Streams sowie für Live- und VOD-Streams. Wenn Sie festlegen möchten, welcher Stream wiedergegeben wird, aktualisieren Sie die Variable CONTENT_TYPE.

   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

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

   Damit DAI funktioniert, muss der Player ID3-Ereignisse an das IMA DAI SDK übergeben. Die Methode callback.onUserTextReceived() führt dies im folgenden Beispielcode aus.

   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

3. Fügen Sie eine buildStreamRequest()-Methode hinzu, um die SteamRequest zu erstellen. Bei dieser Methode wird zwischen verschiedenen Streams gewechselt, je nachdem, wie Sie die Variable CONTENT_TYPE festlegen. Der in dieser Anleitung verwendete Standardstream ist der HLS-VOD-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

4. Außerdem benötigen Sie ein 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

5. 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 abgespielt werden. Da sich Content und Anzeigen in einem Stream befinden, müssen Sie bereit sein, einen Fallback-Stream aufzurufen, wenn beim DAI-Stream 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

6. 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

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

   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

8. 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

9. Ändern Sie die Layoutdatei activity_my.xml der Aktivität, um UI-Elemente für die Anmeldung 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 fordern jetzt Videoanzeigen in Ihrer Android-App an und präsentieren sie. Informationen zum Optimieren der Implementierung finden Sie unter Lesezeichen, Snapback und in der API-Dokumentation.

Fehlerbehebung

Wenn Sie Probleme bei der Wiedergabe einer Videoanzeige haben, laden Sie 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.