IMA SDK 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 den clientseitigen IMA SDKs behalten Sie die Kontrolle über die Wiedergabe von Videoinhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer für die Inhalte der App positioniert ist.

In dieser Anleitung wird gezeigt, wie Sie das IMA SDK in eine einfache Videoplayer-App einbinden. Wenn Sie sich eine vollständige Beispielintegration ansehen oder ihr folgen möchten, laden Sie das einfache Beispiel von GitHub herunter. Wenn Sie einen HTML5-Player mit vorab integriertem SDK verwenden möchten, sehen Sie sich das IMA SDK-Plug-in für Video.js an.

IMA-Clientseite – Übersicht

Die clientseitige Implementierung von IMA umfasst vier Haupt-SDK-Komponenten, die in diesem Leitfaden beschrieben werden:

  • AdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA Benutzeroberflächenelemente für Anzeigen rendert und die Sichtbarkeit misst, einschließlich Active View und Open Measurement.
  • AdsLoader: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur einen Anzeigen-Loader instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Ein Objekt, das eine Anzeigenanfrage definiert. In Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie die 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.

Vorbereitung

Für den Start ist Folgendes erforderlich:

  • Drei leere Dateien:
    • index.html
    • style.css
    • ads.js
  • Python auf Ihrem Computer installiert oder ein Webserver zum Testen

1. Entwicklungsserver starten

Da das IMA SDK Abhängigkeiten mit demselben Protokoll wie die Seite lädt, von der es geladen wird, müssen Sie einen Webserver verwenden, um Ihre App zu testen. Am einfachsten starten Sie einen lokalen Entwicklungsserver mit dem integrierten Server von Python.

  1. Führen Sie über die Befehlszeile im Verzeichnis, das Ihre Datei „index.html“ enthält, folgenden Befehl aus: 
      python -m http.server 8000
  2. Rufen Sie in einem Webbrowser http://localhost:8000/ 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 umschließenden Element enthalten ist, sowie eine Schaltfläche zum Starten der Wiedergabe. Im folgenden Beispiel wird das IMA SDK importiert und das Containerelement AdDisplayContainer eingerichtet. Weitere Informationen finden Sie in den Schritten IMA SDK importieren und Anzeigencontainer erstellen . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Fügen Sie die erforderlichen Tags hinzu, um die Dateien style.css und ads.js zu laden. Ändern Sie dann styles.css, damit der Videoplayer auf Mobilgeräten responsiv ist. Deklarieren Sie schließlich in ads.js Ihre Variablen und lösen Sie die Videowiedergabe aus, wenn Sie auf die Wiedergabeschaltfläche klicken.

Das Code-Snippet ads.js enthält einen Aufruf von setUpIMA(), der im Abschnitt Initialize the AdsLoader and make an ads request definiert ist.

3. IMA SDK importieren

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. Anzeigencontainer erstellen

In den meisten Browsern verwendet das IMA SDK ein spezielles Anzeigencontainer-Element, um sowohl Anzeigen als auch UI-Elemente im Zusammenhang mit Anzeigen darzustellen. Dieser Container muss so dimensioniert sein, dass er das Videoelement von der oberen linken Ecke aus überlagert. Die Höhe und Breite der Anzeigen, die in diesem Container platziert werden, werden durch das adsManager-Objekt festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

Um dieses Anzeigencontainer-Element zu implementieren, erstellen Sie zuerst ein neues div-Element innerhalb des video-container-Elements. Aktualisieren Sie dann das CSS, um das Element in der linken oberen Ecke des video-element zu positionieren. Fügen Sie zum Schluss die Funktion createAdDisplayContainer() hinzu, um das AdDisplayContainer-Objekt mit dem neuen Anzeigencontainer div zu erstellen. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. AdsLoader initialisieren und Anzeigenanfrage stellen

Wenn Sie Anzeigen anfordern möchten, erstellen Sie eine AdsLoader-Instanz. Der AdsLoader-Konstruktor akzeptiert ein AdDisplayContainer-Objekt als Eingabe und kann verwendet werden, um AdsRequest-Objekte zu verarbeiten, die einer bestimmten Ad-Tag-URL zugeordnet sind. Das in diesem Beispiel verwendete Anzeigen-Tag enthält eine 10-sekündige Pre-Roll-Anzeige. Sie können diese oder eine beliebige andere Anzeigen-Tag-URL mit dem IMA Video Suite Inspector testen.

Es hat sich bewährt, nur eine Instanz von AdsLoader für den gesamten Lebenszyklus einer Seite zu verwenden. Wenn Sie zusätzliche Anzeigenanfragen stellen möchten, erstellen Sie ein neues AdsRequest-Objekt, verwenden Sie aber dieselbe AdsLoader. Weitere Informationen finden Sie in den IMA SDK-FAQs.

Mit AdsLoader.addEventListener können Sie auf Ereignisse wie „Anzeigen geladen“ und „Fehler“ reagieren. Die folgenden Ereignisse können beobachtet werden:

  • ADS_MANAGER_LOADED
  • AD_ERROR

So erstellen Sie die Listener onAdsManagerLoaded() und onAdError(): 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Auf AdsLoader-Ereignisse reagieren

Wenn das AdsLoader Anzeigen erfolgreich lädt, wird das Ereignis ADS_MANAGER_LOADED ausgegeben. Parst das an den Callback übergebene Ereignis, um das AdsManager-Objekt zu initialisieren. Mit AdsManager werden die einzelnen Anzeigen geladen, die durch die Antwort auf die Anzeigen-Tag-URL definiert sind.

Behandeln Sie alle Fehler, die während des Ladevorgangs auftreten. Wenn Anzeigen nicht geladen werden, muss die Medienwiedergabe ohne Anzeigen fortgesetzt werden, damit die Nutzer den Content ansehen können. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Weitere Informationen zu den in der Funktion onAdsManagerLoaded() festgelegten Listenern finden Sie in den folgenden Unterabschnitten:

AdsManager-Fehler beheben

Der für AdsLoader erstellte Fehler-Handler kann auch als Fehler-Handler für AdsManager dienen. Hier sehen Sie den Ereignishandler, der die Funktion onAdError() wiederverwendet. 

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

Wiedergabe- und Pause-Ereignisse verarbeiten

Wenn das AdsManager bereit ist, eine Anzeige einzufügen, wird das CONTENT_PAUSE_REQUESTED-Ereignis ausgelöst. Behandle dieses Ereignis, indem du eine Pause im zugrunde liegenden Videoplayer auslöst. Wenn eine Anzeige ausgeliefert wurde, löst AdsManager das Ereignis CONTENT_RESUME_REQUESTED aus. Reagiere auf dieses Ereignis, indem du die Wiedergabe des zugrunde liegenden Inhaltsvideos neu startest. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Definitionen der Funktionen onContentPauseRequested() und onContentResumeRequested() finden Sie im folgenden Beispiel: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Wiedergabe von Inhalten während nicht linearer Anzeigen

Der AdsManager pausiert das Video, wenn eine Anzeige abgespielt werden soll. Dieses Verhalten wird jedoch nicht bei nicht linearen Anzeigen berücksichtigt, bei denen der Inhalt während der Anzeigenschaltung weiter abgespielt wird. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Um nicht lineare Anzeigen zu unterstützen, müssen Sie auf das LOADED-Ereignis warten, das von AdsManager ausgegeben wird. Prüfen Sie, ob die Anzeige linear ist. Wenn nicht, setzen Sie die Wiedergabe im Videoelement fort.

Die Definition der Funktion onAdLoaded() finden Sie im folgenden Beispiel. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Klick zum Pausieren auf Mobilgeräten auslösen

Da das AdContainer das Videoelement überlagert, können Nutzer nicht direkt mit dem zugrunde liegenden Player interagieren. Das kann Nutzer auf Mobilgeräten verwirren, die erwarten, dass sie 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 weiter, wo sie verarbeitet werden können. Dies gilt nicht für lineare Anzeigen in Browsern, die nicht auf Mobilgeräten verwendet werden, da durch Klicken auf die Anzeige der Klicklink geöffnet wird.

Wenn Sie die Funktion „Klicken, um zu pausieren“ implementieren möchten, fügen Sie dem Listener für das Laden des Fensters die adContainerClick()-Klick-Handler-Funktion hinzu. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. AdsManager starten

Um die Anzeigenwiedergabe zu starten, müssen Sie die AdsManager initiieren und starten. Um mobile Browser vollständig zu unterstützen, in denen Anzeigen nicht automatisch abgespielt werden können, müssen Sie die Anzeigenwiedergabe über Nutzerinteraktionen mit der Seite auslösen, z. B. durch Klicken auf die Schaltfläche „Wiedergabe“. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Ändern der Größe des Players unterstützen

Damit Anzeigen dynamisch an die Größe eines Videoplayers oder an Änderungen der Bildschirmausrichtung angepasst werden, rufen Sie adsManager.resize() als Reaktion auf Ereignisse zur Fenstergrößenänderung auf. 

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

Geschafft! 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 in den Beispielen auf GitHub.