Diese Seite wurde von der Cloud Translation API übersetzt.

Jetzt loslegen

Mit IMA SDKs können Sie ganz einfach Multimedia-Anzeigen 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 clientseitigen IMA SDKs haben Sie die Kontrolle über die Videowiedergabe im Content, 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 fertige Beispielintegration ansehen oder sie verfolgen möchten, laden Sie das einfache Beispiel von GitHub herunter. Wenn Sie an einem HTML5-Player mit vorintegriertem SDK interessiert sind, finden Sie entsprechende Informationen unter IMA SDK-Plug-in für Video.js.

IMA-Clientseite – Übersicht

Die Implementierung der IMA Client-Seite umfasst vier SDK-Hauptkomponenten, die in diesem Leitfaden erläutert werden:

AdDisplayContainer: Ein Containerobjekt, in dem die Anzeigen gerendert werden.
AdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Anzeigenanfragen antwortet. Sie sollten nur einen Anzeigenlader 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 lädt wie die Seite, von der es geladen wird, müssen Sie einen Webserver zum Testen Ihrer App verwenden. Die einfachste Methode, einen lokalen entwicklungsserver zu starten, besteht in der Verwendung des integrierten Servers von Python.

Über die Befehlszeile aus dem Verzeichnis, das die Datei „index.html“ enthält:
```
  python -m http.server 8000
```
Hinweis:http.server ist nur in Python 3.x verfügbar.
Rufen Sie http://localhost:8000/ in einem Webbrowser auf.

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

2. Einen 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, um die Wiedergabe auszulösen. Fügen Sie außerdem die erforderlichen Tags hinzu, um die Dateien style.css und ads.js zu laden. Ändern Sie dann styles.css, damit der Videoplayer für Mobilgeräte angepasst wird. In ads.js wird 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();
  });
});

Nachdem du diesen Schritt abgeschlossen hast und dann index.html in deinem Browser öffnest (über deinen Entwicklungsserver), sollte das Videoelement angezeigt werden. Das Video sollte gestartet werden, wenn du auf die Wiedergabeschaltfläche klickst.

3. IMA SDK importieren

Als Nächstes fügen Sie 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

Um das Verhalten des Videoplayers mit JavaScript zu ändern, füge Event-Handler hinzu, die die folgenden Aktionen auslösen:

Initialisieren Sie nach dem Laden der Seite das IMA SDK.
Wenn auf die Videowiedergabeschaltfläche geklickt wird, werden die Anzeigen geladen (es sei denn, es wurden bereits Anzeigen geladen).
Aktualisiere die Größe des Browserfensters und die adsManager-Größe, um die Seite für Mobilgeräte anzupassen.

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

In den meisten Browsern wird für das IMA SDK ein eigenes Anzeigencontainer-Element verwendet, mit dem sowohl Anzeigen als auch anzeigenbezogene UI-Elemente dargestellt werden. Dieser Container muss die Größe haben, damit das Videoelement oben links eingeblendet wird. Die Höhe und Breite der Anzeigen in diesem Container werden über das adsManager-Objekt festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

Um dieses Anzeigencontainerelement zu implementieren, müssen Sie zuerst ein neues div innerhalb des video-container-Elements erstellen. Aktualisieren Sie dann das CSS, damit das Element oben links in video-element positioniert wird. Definieren Sie abschließend 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 eine Anzeigenanfrage senden

Um eine Gruppe von Anzeigen anzufordern, erstellen Sie eine ima.AdsLoader-Instanz. Diese Instanz verwendet ein AdDisplayContainer-Objekt als Eingabe und kann verwendet werden, um ima.AdsRequest-Objekte zu verarbeiten, die mit einer bestimmten Anzeigen-Tag-URL verknüpft sind. Das in diesem Beispiel verwendete Anzeigen-Tag enthält eine 10-sekündige Pre-Roll-Anzeige. Du kannst diese oder beliebige Anzeigen-Tag-URLs mit dem IMA Video Suite Inspector testen.

Als Best Practice gilt: Führen Sie nur eine Instanz von ima.AdsLoader für den gesamten Lebenszyklus einer Seite aus. Wenn Sie weitere Anzeigenanfragen senden möchten, erstellen Sie ein neues ima.AdsRequest-Objekt. Verwenden Sie dabei dasselbe ima.AdsLoader-Objekt. Weitere Informationen finden Sie unter IMA SDK – FAQs.

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 die Anzeigen erfolgreich geladen wurden, gibt ima.AdsLoader ein ADS_MANAGER_LOADED-Ereignis aus. Das an das Callback übergebene Ereignis parsen, um das AdsManager-Objekt zu initialisieren Mit AdsManager werden die einzelnen Anzeigen geladen, wie in der Antwort auf die Anzeigen-Tag-URL definiert.

Außerdem sollten Sie alle Fehler beheben, die während des Ladevorgangs auftreten können. Wenn Anzeigen nicht geladen werden, sollte die Medienwiedergabe ohne Werbeanzeigen fortgesetzt werden, um die Nutzererfahrung nicht zu beeinträchtigen.

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

Zum Starten der Anzeigenwiedergabe müssen Sie den 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 Anzeigen dynamisch an die Größe des Videoplayers angepasst werden, muss bei Änderungen am Bildschirmgröße oder -ausrichtung 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. AdsManager-Ereignisse beobachten

AdsManager löst auch mehrere Ereignisse aus, die verarbeitet werden müssen. Diese Ereignisse werden verwendet, um Statusänderungen zu verfolgen, die Wiedergabe im Content-Video auszulösen und zu pausieren und Fehler zu registrieren.

Fehlerbehebung

Der für AdsLoader erstellte Fehler-Handler kann als Fehler-Handler für AdsManager verwendet werden. Fügen Sie dazu einen neuen Event-Handler mit derselben Callback-Funktion hinzu.

ads.js

...

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

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

...

Auslösen von Wiedergabe- und Pausenereignissen

Wenn die AdsManager bereit ist, eine Anzeige für die Auslieferung einzufügen, wird das Ereignis CONTENT_PAUSE_REQUESTED ausgelöst. Lösen Sie dieses Ereignis aus, indem Sie eine Pause für den zugrunde liegenden Videoplayer auslösen. Sobald eine Anzeige abgeschlossen ist, löst AdsManager das Ereignis CONTENT_RESUME_REQUESTED aus. Bearbeiten Sie dieses Ereignis, indem Sie die Wiedergabe für das zugrunde liegende Video wieder 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. Das kann Nutzer auf Mobilgeräten verwirren, da sie voraussichtlich auf einen Videoplayer tippen können, um die Wiedergabe zu pausieren. Um dieses Problem zu beheben, leitet das IMA SDK alle Klicks, die nicht von IMA verarbeitet werden, vom Anzeigen-Overlay an das AdContainer-Element, wo es verarbeitet werden kann. Dies gilt nicht für lineare Anzeigen in Browsern, die nicht für Mobilgeräte optimiert sind, da beim Klicken auf die Anzeige der Klicklink 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 für nicht lineare Anzeigen auslösen

Mit AdsManager wird das Contentvideo pausiert, wenn eine Anzeige für die Auslieferung bereit ist. Nicht lineare Anzeigen werden allerdings nicht berücksichtigt, wenn der Content weiter wiedergegeben werden soll, während die Anzeige eingeblendet wird. Damit nicht lineare Anzeigen unterstützt werden, muss AdsManager auf das Ereignis LOADED ausgegeben werden. Prüfen Sie dann, ob die Anzeige linear ist. Wenn nicht, setzen Sie die Wiedergabe für das 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. Weitere Informationen zu erweiterten SDK-Features finden Sie in den anderen Leitfäden oder in den Beispielen auf GitHub.

Jetzt loslegen

IMA-Clientseite – Übersicht

Voraussetzungen

1. Entwicklungsserver starten

2. Einen einfachen Videoplayer erstellen

3. IMA SDK importieren

4. Seiten- und Videoplayer-Handler anhängen

5. Anzeigencontainer erstellen

6. „AdsLoader“ initialisieren und eine Anzeigenanfrage senden

7. AdsLoader-Ereignisse beobachten

8. AdsManager starten

9. AdsManager responsiv machen

10. AdsManager-Ereignisse beobachten

Fehlerbehebung

Auslösen von Wiedergabe- und Pausenereignissen

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

Wiedergabe für nicht lineare Anzeigen auslösen