Jetzt starten

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 Sie das IMA SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich eine abgeschlossene Beispielintegration ansehen oder diese mitlesen möchten, laden Sie das einfache Beispiel von GitHub herunter. Wenn Sie an einem HTML5-Player mit vorinstalliertem SDK interessiert sind, sehen Sie sich das IMA SDK-Plug-in für Video.js an.

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

Für den Start ist Folgendes erforderlich:

  • Drei leere Dateien:
    • index.html
    • style.css
    • ads.js
  • Auf Ihrem Computer installierter Python-Code oder ein Webserver zum Testen

1. Entwicklungsserver starten

Da das IMA SDK Abhängigkeiten über dasselbe Protokoll wie die Seite lädt, von der es geladen wird, müssen Sie Ihre Anwendung mit einem Webserver testen. Die einfachste Möglichkeit zum Starten eines lokalen Entwicklungsservers ist die Verwendung des integrierten Python-Servers.

  1. Verwenden Sie eine Befehlszeile aus dem Verzeichnis, das die Datei index.html enthält:
      python -m http.server 8000
    
  2. Rufe in einem Webbrowser http://localhost:8000/ auf.

Sie können auch einen beliebigen anderen Webserver wie den Apache-HTTP-Server verwenden.

2. Einfachen Videoplayer erstellen

Ändern Sie zuerst index.html, um ein einfaches HTML5-Videoelement zu erstellen, das in einem Wrapping-Element enthalten ist, und eine Schaltfläche zum Auslösen der Wiedergabe. Fügen Sie außerdem die erforderlichen Tags zum Laden der Dateien style.css und ads.js hinzu. Passe dann styles.css an, damit der Videoplayer für Mobilgeräte responsiv wird. Schließlich wird in ads.js die Videowiedergabe ausgelöst, wenn auf die Wiedergabeschaltfläche geklickt wird.

index.html

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>

style.css
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

Wenn Sie index.html in Ihrem Browser öffnen (über den Entwicklungsserver), sollten Sie das Videoelement sehen können. Das Video sollte gestartet werden, wenn Sie auf die Wiedergabeschaltfläche klicken.

3. IMA SDK importieren

Fügen Sie als Nächstes das IMA-Framework mit einem Skript-Tag in index.html vor dem Tag für ads.js ein.

index.html
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Seiten- und Videoplayer-Handler anhängen

Wenn du das Verhalten des Videoplayers mit JavaScript ändern möchtest, musst du Event-Handler hinzufügen, die die folgenden Aktionen auslösen:

  • Initialisieren Sie nach Abschluss des Ladevorgangs der Seite das IMA SDK.
  • Wenn auf die Videowiedergabeschaltfläche geklickt wird, werden die Anzeigen geladen (es sei denn, es sind bereits Anzeigen geladen).
  • Aktualisiere die Größe des Videoelements und der adsManager-Dimensionen, wenn die Größe des Browserfensters angepasst wird, damit die Seite für Mobilgeräte responsiv ist
ads.js
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. Anzeigencontainer erstellen

In den meisten Browsern wird für das IMA SDK ein eigenes Anzeigencontainerelement verwendet, um sowohl Anzeigen als auch anzeigenbezogene UI-Elemente einzublenden. Dieser Container muss so groß sein, dass das Videoelement von der linken oberen Ecke überlagert wird. Höhe und Breite der Anzeigen in diesem Container werden vom Objekt adsManager festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

Erstellen Sie zum Implementieren dieses Anzeigencontainerelements zuerst eine neue div im Element video-container. Aktualisieren Sie dann das CSS, um das Element oben links im video-element zu positionieren. Definieren Sie abschließend eine Variable für den Container innerhalb der Funktion initializeIMA(), die beim Laden der Seite ausgeführt wird.

index.html
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. AdsLoader initialisieren und eine Anzeigenanfrage senden

Erstellen Sie eine ima.AdsLoader-Instanz, um eine Gruppe von Anzeigen anzufordern. Diese Instanz verwendet ein AdDisplayContainer-Objekt als Eingabe und kann zur Verarbeitung von ima.AdsRequest-Objekten verwendet werden, die einer angegebenen Anzeigen-Tag-URL zugeordnet sind. Das in diesem Beispiel verwendete Anzeigen-Tag enthält eine 10 Sekunden lange Pre-Roll-Anzeige. Sie können diese oder eine beliebige Anzeigen-Tag-URL mit dem IMA Video Suite Inspector testen.

Als Best Practice hat es sich bewährt, nur eine Instanz von ima.AdsLoader für den gesamten Lebenszyklus einer Seite zu verwalten. Wenn Sie weitere Anzeigenanfragen senden möchten, erstellen Sie ein neues ima.AdsRequest-Objekt, verwenden Sie dann dieselbe ima.AdsLoader. Weitere Informationen finden Sie in den häufig gestellten Fragen zum IMA SDK.

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = '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=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. AdsLoader-Ereignisse beobachten

Wenn Anzeigen erfolgreich geladen wurden, gibt ima.AdsLoader ein ADS_MANAGER_LOADED-Ereignis aus. Parst das an den Callback übergebene Ereignis, um das AdsManager-Objekt zu initialisieren. Mit AdsManager werden die einzelnen Anzeigen gemäß der Antwort auf die Anzeigen-Tag-URL geladen.

Achten Sie außerdem auf Fehler, die während des Ladevorgangs auftreten können. Wenn Anzeigen nicht geladen werden, achten Sie darauf, dass die Medienwiedergabe ohne Werbung fortgesetzt wird, damit die Nutzererfahrung nicht beeinträchtigt wird.

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. AdsManager starten

Um die Wiedergabe der Anzeige zu starten, müssen Sie AdsManager starten. Damit mobile Browser vollständig unterstützt werden, sollte dies durch eine Nutzerinteraktion ausgelöst werden.

ads.js
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. AdsManager responsiv machen

Damit sich die Größe der Anzeigen dynamisch an die Größe des Videoplayers anpasst, muss bei der Änderung der Bildschirmgröße oder -ausrichtung das Ereignis adsManager.resize() zur Größenanpassung des Fensters aufgerufen werden.

ads.js
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. AdsManager-Ereignisse beobachten

AdsManager löst außerdem mehrere Ereignisse aus, die verarbeitet werden müssen. Diese Ereignisse werden verwendet, um Statusänderungen zu erfassen, die Wiedergabe zu starten und zu pausieren und Fehler zu registrieren.

Fehlerbehebung

Der für AdsLoader erstellte Fehler-Handler kann als Fehler-Handler für AdsManager dienen. Dazu wird ein neuer Event-Handler mit derselben Callback-Funktion hinzugefügt.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

Wiedergabe- und Pausenereignisse auslösen

Wenn die AdsManager zur Auslieferung einer Anzeige bereit ist, wird das Ereignis CONTENT_PAUSE_REQUESTED ausgelöst. Lösen Sie dieses Ereignis aus, indem Sie im zugrunde liegenden Videoplayer eine Pause auslösen. Entsprechend löst AdsManager das Ereignis CONTENT_RESUME_REQUESTED aus, wenn eine Anzeige abgeschlossen ist. Verarbeiten Sie dieses Ereignis, indem Sie die Wiedergabe im zugrunde liegenden Inhaltsvideo neu starten.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

Click-to-Pause auf Mobilgeräten auslösen

Da AdContainer das Videoelement überlagert, können Nutzer nicht direkt mit dem zugrunde liegenden Player interagieren. Dies kann Nutzer auf Mobilgeräten verwirren, da sie voraussichtlich auf einen Videoplayer tippen müssen, um die Wiedergabe zu pausieren. Zur Behebung dieses Problems leitet das IMA SDK alle Klicks, die nicht von IMA verarbeitet werden, vom Anzeigen-Overlay an das AdContainer-Element weiter, wo sie verarbeitet werden können. Dies gilt nicht für lineare Anzeigen in Browsern, die nicht zum Mobilgerät gehören, da durch einen Klick auf die Anzeige der Klick-Link geöffnet wird.

Zur Implementierung von Click-to-Pause fügen Sie einen Klick-Handler zu AdContainer hinzu und lösen Wiedergabe- oder Pausenereignisse für das zugrunde liegende Video aus.

ads.js
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Wiedergabe bei nicht linearen Anzeigen auslösen

Mit AdsManager wird das Contentvideo pausiert, sobald eine Anzeige wiedergegeben werden kann. Nicht lineare Anzeigen, in denen die Inhalte während der Anzeigenwiedergabe wiedergegeben werden sollten, werden jedoch nicht berücksichtigt. Damit nicht lineare Anzeigen unterstützt werden, muss AdsManager das Ereignis LOADED ausgeben. Prüfen Sie dann, ob die Anzeige linear ist. Wenn nicht, setzen Sie die Wiedergabe im Videoelement fort.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

Fertig! Mit dem IMA SDK werden jetzt Anzeigen angefordert und ausgeliefert. Informationen zu erweiterten SDK-Features finden Sie in den anderen Leitfäden oder in den Beispielen auf GitHub.