Erste Schritte

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

In diesem Leitfaden wird erläutert, wie Sie das IMA SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich eine fertige Beispielintegration ansehen oder dem Beispiel folgen 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.

IMA – clientseitige Übersicht

Die clientseitige Implementierung von IMA umfasst vier SDK-Hauptkomponenten, die in dieser Anleitung beschrieben werden:

  • 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. Bei Anzeigenanfragen wird 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 auf Anzeigenereignisse wartet, die vom SDK ausgelöst werden.

Voraussetzungen

Für den Start ist Folgendes erforderlich:

  • Drei leere Dateien:
    • index.html
    • style.css
    • ads.js
  • Auf Ihrem Computer installierter Python oder 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 Methode zum Starten eines lokalen Entwicklungsservers ist die Verwendung des integrierten Python-Servers.

  1. Führen Sie über eine Befehlszeile in dem Verzeichnis, das die Datei „index.html“ enthält, folgenden Befehl aus:
      python -m http.server 8000
    
  2. Rufe http://localhost:8000/ in einem Webbrowser auf.

Sie können auch einen anderen Webserver verwenden, z. B. den Apache HTTP Server.

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 Tags hinzu, die zum Laden der Dateien style.css und ads.js erforderlich sind. Ändere dann styles.css, damit der Videoplayer für Mobilgeräte responsiv ist. Lösen Sie schließlich in ads.js die Videowiedergabe aus, 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();
  });
});

Nachdem Sie diesen Schritt ausgeführt haben, sollten Sie das Videoelement sehen können, wenn Sie index.html in Ihrem Browser öffnen (über Ihren Entwicklungsserver), und das Video sollte starten, wenn Sie auf die Wiedergabeschaltfläche klicken.

3. IMA SDK importieren

Fügen Sie als Nächstes das IMA-Framework mithilfe eines Skript-Tags in der Datei 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, kannst du Event-Handler hinzufügen, die die folgenden Aktionen auslösen:

  • Wenn die Seite fertig geladen ist, initialisieren Sie das IMA SDK.
  • Wenn auf die Wiedergabeschaltfläche des Videos geklickt wird, werden die Anzeigen geladen (es sei denn, es wurden bereits Anzeigen geladen).
  • Wenn die Größe des Browserfensters angepasst wird, aktualisieren Sie das Videoelement und die Abmessungen adsManager, um die Seite für Mobilgeräte responsiv zu machen.
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 im IMA SDK ein eigenes Anzeigencontainerelement verwendet, um sowohl Anzeigen als auch anzeigenbezogene UI-Elemente darzustellen. Dieser Container muss so groß sein, dass er das Videoelement von der oberen linken Ecke überlagert. Höhe und Breite der in diesem Container platzierten Anzeigen werden mit dem adsManager-Objekt festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

Erstellen Sie zuerst ein neues div-Element im video-container-Element, um dieses Anzeigencontainerelement zu implementieren. Aktualisieren Sie dann den CSS-Code, um das Element in der oberen linken Ecke von video-element zu positionieren. Definieren Sie schließlich eine Variable für den Container in 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 Anzeigenanfrage senden

Erstellen Sie eine ima.AdsLoader-Instanz, um einen Satz von Anzeigen anzufordern. Diese Instanz verwendet ein AdDisplayContainer-Objekt als Eingabe und kann zur Verarbeitung von ima.AdsRequest-Objekten verwendet werden, die mit einer angegebenen Anzeigen-Tag-URL verknüpft 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.

Es hat sich bewährt, nur eine Instanz von ima.AdsLoader für den gesamten Lebenszyklus einer Seite beizubehalten. Wenn Sie weitere Anzeigenanfragen senden möchten, erstellen Sie ein neues ima.AdsRequest-Objekt, aber verwenden Sie dasselbe ima.AdsLoader-Objekt noch einmal. Weitere Informationen finden Sie in den FAQ 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. Auf AdsLoader-Ereignisse warten

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 dem AdsManager werden die einzelnen Anzeigen gemäß der Antwort auf die Anzeigen-Tag-URL geladen.

Achten Sie außerdem darauf, Fehler zu beheben, die möglicherweise während des Ladevorgangs auftreten. Wenn Anzeigen nicht geladen werden, achte darauf, dass die Medienwiedergabe ohne Werbeunterbrechungen 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 Anzeigenwiedergabe 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 die Größe der Anzeigen dynamisch an die Größe des Videoplayers angepasst wird, muss bei einer Änderung der Größe oder Ausrichtung des Bildschirms adsManager.resize() 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. Auf AdsManager-Ereignisse warten

Das AdsManager löst außerdem mehrere Ereignisse aus, die verarbeitet werden müssen. Diese Ereignisse werden verwendet, um Statusänderungen zu verfolgen, die Wiedergabe und Pause des Inhaltsvideos auszulösen 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 mit dem AdsManager eine Anzeige zur Auslieferung eingefügt werden kann, wird das Ereignis CONTENT_PAUSE_REQUESTED ausgelöst. Lösen Sie bei diesem Ereignis eine Pause im zugrunde liegenden Videoplayer ein. Wenn eine Anzeige vollständig wiedergegeben wurde, löst AdsManager das Ereignis CONTENT_RESUME_REQUESTED aus. Verarbeite dieses Ereignis, indem du die Wiedergabe des zugrunde liegenden Inhaltsvideos neu startest.

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

Auf Mobilgeräten klicken, um zu pausieren

Da AdContainer das Videoelement überlagert, können Nutzer nicht direkt mit dem zugrunde liegenden Player interagieren. Das kann für Nutzer von Mobilgeräten verwirrend sein, die erwarten, dass sie auf einen Videoplayer tippen können, um die Wiedergabe zu pausieren. Zur Behebung dieses Problems übergibt das IMA SDK alle Klicks, die nicht von IMA aus dem Anzeigen-Overlay verarbeitet werden, an das AdContainer-Element, wo sie verarbeitet werden können. Dies gilt nicht für lineare Anzeigen in nicht mobilen Browsern, da durch einen Klick auf die Anzeige der Klicklink geöffnet wird.

Wenn Sie die Funktion „Zum Pausieren klicken“ implementieren möchten, fügen Sie AdContainer einen Klick-Handler hinzu und lösen Sie 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, wenn eine Anzeige zur Wiedergabe bereit ist. Dies gilt jedoch nicht für nicht lineare Anzeigen, bei denen der Content weiter abgespielt werden soll, während die Anzeige zu sehen ist. Damit nicht lineare Anzeigen unterstützt werden, muss AdsManager auf das Ereignis LOADED warten. Prüfen Sie dann, ob die Anzeige linear ist. Ist dies nicht der Fall, setzen Sie die Wiedergabe auf dem 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! Sie fordern jetzt Anzeigen mit dem IMA SDK an und präsentieren sie. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder den Beispielen auf GitHub.