IMA SDK einrichten

Plattform auswählen: HTML5 Android iOS tvOS

Mit den IMA SDKs lassen sich Multimediaanzeigen ganz einfach in Websites und Apps einbinden. IMA SDKs können Anzeigen von jedem VAST-konformen Ad-Server anfordern und die Anzeigenauslieferung in Ihren Apps verwalten. Mit den clientseitigen IMA SDKs, behalten Sie die Kontrolle über die Wiedergabe von Videoinhalten, während das SDK die Anzeigenauslieferung ü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 eine vollständige Beispielintegration ansehen oder nachvollziehen möchten, laden Sie das einfache Beispiel von GitHub herunter. Wenn Sie einen HTML5-Player mit vorintegriertem SDK verwenden möchten, sehen Sie sich das IMA SDK-Plug-in für Video.js an.

Übersicht über die clientseitige IMA-Implementierung

Die clientseitige IMA-Implementierung umfasst vier Hauptkomponenten des SDK, die in dieser Anleitung beschrieben 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 ein Anzeigenladeprogramm instanziieren, das 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 Anzeigengrößen angegeben.
  • AdsManager: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenauslieferung steuert und auf Anzeigen ereignisse 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 für Tests

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 über die Befehlszeile im Verzeichnis mit der Datei „index.html“ 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 in einem umschließenden Element und eine Schaltfläche zum Auslösen der Wiedergabe zu erstellen. Im folgenden Beispiel wird das IMA SDK importiert und das AdDisplayContainer Containerelement 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>

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

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 Schaltfläche „Wiedergabe“ klicken.

Beachten Sie, dass das Code-Snippet ads.js einen Aufruf von setUpIMA() enthält, der im Abschnitt Anzeigenladeprogramm initialisieren und Anzeigenanfrage senden definiert ist.

3. IMA SDK importieren

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

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

4. Anzeigencontainer erstellen

In den meisten Browsern verwendet das IMA SDK ein spezielles Anzeigencontainerelement, um sowohl Anzeigen als auch UI-Elemente für Anzeigen zu präsentieren. 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 vom adsManager Objekt festgelegt. Sie müssen diese Werte also nicht manuell festlegen.

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

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

5. Anzeigenladeprogramm initialisieren und Anzeigenanfrage senden

Erstellen Sie eine AdsLoader Instanz, um Anzeigen anzufordern. Der AdsLoader Konstruktor verwendet ein AdDisplayContainer Objekt als Eingabe und kann zum Verarbeiten AdsRequest Objekte 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 andere Anzeigen-Tag-URL mit dem IMA Video Suite Inspector testen.

Als Best Practice sollten Sie nur eine Instanz von AdsLoader für den gesamten Lebenszyklus einer Seite verwenden. Wenn Sie weitere Anzeigenanfragen senden möchten, erstellen Sie ein neues AdsRequest -Objekt, verwenden Sie aber dasselbe AdsLoader. Weitere Informationen finden Sie in den IMA SDK-FAQs.

Verwenden Sie AdsLoader.addEventListener, um auf geladene Anzeigen und Fehlerereignisse zu warten und darauf zu reagieren. Warten Sie auf die folgenden Ereignisse:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Im folgenden Beispiel wird gezeigt, wie Sie die onAdsManagerLoaded() und onAdError() Listener erstellen: 

/**
 * 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);
}

6. Auf AdsLoader-Ereignisse reagieren

Wenn das AdsLoader Anzeigen erfolgreich lädt, wird ein ADS_MANAGER_LOADED Ereignis ausgelöst. Analysieren Sie das an den Callback übergebene Ereignis, um das AdsManager Objekt zu initialisieren. Der AdsManager lädt die einzelnen Anzeigen, wie in der Antwort auf die Anzeigen-Tag-URL definiert.

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 nicht beim Ansehen der Inhalte gestört werden. 

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

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

AdsManager-Fehler behandeln

Der für AdsLoader erstellte Fehler-Handler kann auch als Fehler-Handler für den AdsManager dienen. Sehen Sie sich den Ereignis-Handler an, der die Funktion onAdError() wiederverwendet. 

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

Ereignisse für Wiedergabe und Pause behandeln

Wenn das AdsManager bereit ist, eine Anzeige einzufügen, wird das CONTENT_PAUSE_REQUESTED Ereignis ausgelöst. Behandeln Sie dieses Ereignis, indem Sie die Wiedergabe im zugrunde liegenden Videoplayer pausieren. Wenn eine Anzeige vollständig ausgeliefert wurde, löst das AdsManager das CONTENT_RESUME_REQUESTED Ereignis aus. Behandeln Sie dieses Ereignis, indem Sie die Wiedergabe des zugrunde liegenden Videoinhalts neu starten. 

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

Definitionen der onContentPauseRequested() und onContentResumeRequested() Funktionen 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();
}

Wiedergabe von Inhalten während nicht linearer Anzeigen behandeln

Der AdsManager pausiert das Video mit den Inhalten, wenn eine Anzeige bereit zur Wiedergabe ist. Dieses Verhalten berücksichtigt jedoch keine nicht linearen Anzeigen, bei denen die Wiedergabe der Inhalte fortgesetzt wird, während die Anzeige eingeblendet wird. 

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

Wenn Sie nicht lineare Anzeigen unterstützen möchten, warten Sie darauf, dass das AdsManager das LOADED Ereignis auslöst. Prüfen Sie, ob die Anzeige linear ist. Wenn nicht, setzen Sie die Wiedergabe des Videoelements 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();
  }
}

7. Klick-to-Pause 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, da sie 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-Mobilbrowsern, da durch Klicken auf die Anzeige der Klicklink geöffnet wird.

Um die Klick-to-Pause-Funktion zu implementieren, fügen Sie die adContainerClick() Klick-Handler-Funktion hinzu, die im Listener für das Laden des Fensters aufgerufen wird. 

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

8. `AdsManager` starten

Um die Anzeigenauslieferung zu starten, initialisieren und starten Sie AdsManager. Um mobile Browser vollständig zu unterstützen, in denen Anzeigen nicht automatisch wiedergegeben werden können, lösen Sie die Anzeigenauslieferung durch Nutzerinteraktionen auf der Seite aus, 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();
  }
}

9. Größenänderung des Players unterstützen

Damit die Größe von Anzeigen dynamisch angepasst wird und sie der Größe eines Videoplayers oder Änderungen der Bildschirm ausrichtung entsprechen, rufen Sie adsManager.resize() als Reaktion auf Ereignisse zur Größenänderung des Fensters 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);
  }
});

Jetzt weißt du Bescheid. 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.