Los gehts

Mit IMA SDKs kannst du ganz einfach Multimedia-Anzeigen in deine 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 vom SDK ausgelöste Anzeigenereignisse wartet.

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 über dasselbe 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 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. Fügen Sie auch 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. Starten Sie abschließend in ads.js die Videowiedergabe, 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 nach Abschluss dieses Schritts index.html in Ihrem Browser über Ihren Entwicklungsserver öffnen, sollte das Videoelement sichtbar sein und das Video sollte starten, wenn Sie auf die Wiedergabeschaltfläche klicken.

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.

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, füge Ereignis-Handler hinzu, die die folgenden Aktionen auslösen:

  • Nachdem die Seite geladen wurde, initialisiere das IMA SDK.
  • Wenn auf die Wiedergabeschaltfläche des Videos geklickt wird, werden Anzeigen geladen (sofern noch keine Anzeigen geladen sind).
  • Wenn die Größe des Browserfensters geändert wird, aktualisiere das Videoelement und die adsManager-Abmessungen, 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 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 oben links in der video-element zu positionieren. Definieren Sie abschließend eine Variable für den Container innerhalb der initializeIMA()-Funktion, 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

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie eine ima.AdsLoader-Instanz. Diese Instanz nimmt ein AdDisplayContainer-Objekt als Eingabe entgegen und kann zum Verarbeiten von ima.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 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 aber 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. Auf AdsLoader-Ereignisse warten

Wenn Anzeigen erfolgreich geladen wurden, sendet ima.AdsLoader das Ereignis ADS_MANAGER_LOADED. 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.

Außerdem müssen Sie alle Fehler behandeln, die während des Ladevorgangs auftreten können. Wenn Anzeigen nicht geladen werden, muss die Medienwiedergabe ohne Anzeigen fortgesetzt werden, 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

Wenn du die Wiedergabe der Anzeige starten möchtest, musst du die AdsManager starten. Für die vollständige Unterstützung mobiler Browser 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 gestalten

Damit Anzeigen dynamisch an die Größe des Videoplayers angepasst werden, muss das Ereignis „window resize“ (Fenstergröße ändern) adsManager.resize() aufrufen, wenn sich die Größe oder Ausrichtung des Bildschirms ändert.

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 Ad Manager-Ereignisse warten

Außerdem löst AdsManager mehrere Ereignisse aus, die verarbeitet werden müssen. Mit diesen Ereignissen werden Statusänderungen erfasst, die Wiedergabe und Pause des Inhaltsvideos ausgelöst und Fehler registriert.

Fehlerbehebung

Der für die AdsLoader erstellte Fehlerhandler kann als Fehlerhandler für die AdsManager dienen, indem ein neuer Ereignis-Handler mit derselben Rückruffunktion hinzugefügt wird.

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 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.

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

„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 der AdContainer einen Klick-Handler hinzu und löse Wiedergabe- oder Pausierungsereignisse 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

Der AdsManager hält das Video mit dem Inhalt an, wenn eine Anzeige wiedergegeben werden kann. Bei nicht linearen Anzeigen sollte der Inhalt jedoch weiter abgespielt werden, während die Anzeige eingeblendet wird. Wenn du nicht lineare Anzeigen unterstützen möchtest, musst du das Ereignis AdsManager überwachen, um das Ereignis LOADED zu senden. Prüfen Sie dann, ob die Anzeige linear ist. Falls nicht, fahren Sie mit der Wiedergabe des Videoelements 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();
  }
}

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.