IMA SDK einrichten

Mit IMA SDKs lassen sich Multimedia-Anzeigen ganz einfach in 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 behalten Sie die Kontrolle über die Videowiedergabe von Inhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer der App angezeigt wird.

In dieser Anleitung wird gezeigt, wie du das IMA SDK in eine einfache Videoplayer-App einbindest. Wenn du dir eine fertige Beispielintegration ansehen oder diese Schritt für Schritt nachvollziehen möchtest, lade das einfache Beispiel von GitHub herunter. Wenn du einen HTML5-Player mit vorinstalliertem SDK suchst, sieh dir das IMA SDK-Plug-in für Video.js an.

IMA-Client – Übersicht

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

  • AdDisplayContainer: Ein Containerobjekt, das angibt, wo IMA UI-Elemente 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-Lademechanismus instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.
  • AdsRequest: Objekt, das eine Anzeigenanfrage definiert. In 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 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 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. Die einfachste Möglichkeit, einen lokalen Entwicklungsserver zu starten, ist die Verwendung des integrierten Servers von Python.

  1. Führen Sie in einer Befehlszeile im Verzeichnis, das die Datei index.html enthält, Folgendes 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 in einem Umschlagelement und eine Schaltfläche zum Starten der Wiedergabe zu erstellen. Im folgenden Beispiel wird das IMA SDK importiert und das Containerelement AdDisplayContainer eingerichtet. Weitere Informationen finden Sie unter 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, um den Videoplayer für Mobilgeräte responsiv zu gestalten. Deklarieren Sie abschließend in ads.js Ihre Variablen und lösen Sie die Videowiedergabe aus, wenn auf die Wiedergabeschaltfläche geklickt wird.

Das Code-Snippet ads.js enthält einen Aufruf an setUpIMA(), der im Abschnitt AdsLoader initialisieren und Anzeigenanfrage stellen definiert ist.

3. IMA SDK importieren

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

<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 Anzeigencontainerelement, um sowohl Anzeigen als auch anzeigebezogene UI-Elemente anzuzeigen. Dieser Container muss so groß sein, dass er das Videoelement von der oberen linken Ecke aus überlagert. Höhe und Breite der Anzeigen, die in diesem Container platziert werden, werden vom adsManager-Objekt festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

Wenn Sie dieses Anzeigencontainerelement implementieren möchten, 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 der video-element zu positionieren. Fügen Sie abschließend 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 senden

Wenn Sie Anzeigen anfordern möchten, erstellen Sie eine AdsLoader-Instanz. Der Konstruktor AdsLoader nimmt ein AdDisplayContainer-Objekt als Eingabe an und kann zum Verarbeiten von AdsRequest-Objekten verwendet werden, 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. Sie können diese oder eine beliebige Anzeigen-Tag-URL mit dem IMA Video Suite Inspector testen.

Es empfiehlt sich, nur eine Instanz von AdsLoader für den gesamten Lebenszyklus einer Seite zu verwalten. Wenn Sie weitere Anzeigenanfragen senden möchten, erstellen Sie ein neues AdsRequest-Objekt, verwenden Sie aber dieselbe AdsLoader. Weitere Informationen finden Sie in den häufig gestellten Fragen zum IMA SDK.

Mit AdsLoader.addEventListener können Sie auf geladene Anzeigen und Fehlerereignisse reagieren. Die folgenden Ereignisse können beobachtet werden:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Weitere Informationen zum Erstellen der onAdsManagerLoaded()- und onAdError()-Listener findest du im folgenden Beispiel: 

/**
 * 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&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 = 640;
  adsRequest.linearAdSlotHeight = 400;

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

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Auf AdsLoader-Ereignisse reagieren

Wenn die AdsLoader Anzeigen erfolgreich geladen hat, wird das Ereignis ADS_MANAGER_LOADED ausgegeben. Parse das an den Callback übergebene Ereignis, um das AdsManager-Objekt zu initialisieren. Über das AdsManager werden die einzelnen Anzeigen geladen, wie in der Antwort auf die Anzeigen-Tag-URL definiert.

Beheben Sie alle Fehler, die während des Ladevorgangs auftreten. Wenn Anzeigen nicht geladen werden, muss die Medienwiedergabe ohne Anzeigen fortgesetzt werden, damit die Nutzer die Inhalte ohne Unterbrechungen 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 Listeners, die in der Funktion onAdsManagerLoaded() festgelegt sind, finden Sie in den folgenden Unterabschnitten:

AdsManager-Fehler behandeln

Der für die AdsLoader erstellte Fehler-Handler kann auch als Fehler-Handler für die AdsManager verwendet werden. Weitere Informationen finden Sie im Ereignis-Handler, in dem die Funktion onAdError() wiederverwendet wird. 

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

Wiedergabe- und Pausenereignisse verarbeiten

Wenn die AdsManager bereit ist, eine Anzeige einzufügen, wird das Ereignis CONTENT_PAUSE_REQUESTED ausgelöst. Hier kannst du eine Pause im zugrunde liegenden Videoplayer auslösen. Wenn eine Anzeige beendet wird, löst AdsManager das Ereignis CONTENT_RESUME_REQUESTED aus. Behandle dieses Ereignis, indem du die Wiedergabe des zugrunde liegenden Videocontents 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 bei nicht linearen Anzeigen steuern

Das AdsManager-Symbol pausiert das Video, wenn eine Anzeige wiedergegeben werden kann. Bei nicht linearen Anzeigen, bei denen der Inhalt weiter abgespielt wird, während die Anzeige eingeblendet wird, funktioniert das jedoch nicht. 

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

Wenn du nicht lineare Anzeigen unterstützen möchtest, musst du das Ereignis AdsManager überwachen, um das Ereignis LOADED zu senden. Prüfen Sie, ob die Anzeige linear ist. Falls nicht, fahren Sie mit der Wiedergabe des Videoelements fort.

Die Definition der onAdLoaded()-Funktion 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. „Anklicken 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, übergibt das IMA SDK alle Klicks, die nicht von IMA verarbeitet werden, vom Anzeigen-Overlay an das AdContainer-Element, wo sie verarbeitet werden können. Dies gilt nicht für lineare Anzeigen in nicht mobilen Browsern, da durch Klicken auf die Anzeige der Klicklink geöffnet wird.

Wenn du die Funktion „Anklicken zum Pausieren“ implementieren möchtest, füge die adContainerClick()-Click-Handler-Funktion in den „On Window Load“-Listener ein. 

/**
 * 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

Wenn du die Wiedergabe der Anzeige starten möchtest, starte die AdsManager. Damit mobile Browser vollständig unterstützt werden, in denen Anzeigen nicht automatisch abgespielt werden können, sollten Sie die Anzeigenwiedergabe über Nutzerinteraktionen mit der Seite auslösen, z. B. über das Klicken auf die Wiedergabeschaltfläche. 

/**
 * 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. Größe des Players anpassen

Damit Anzeigen dynamisch die Größe eines Videoplayers annehmen oder sich an Änderungen der Bildschirmausrichtung anpassen, 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 über das IMA SDK an und schalten sie. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.