Jetzt starten

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. IMA SDKs können Anzeigen von beliebigen <ph type="x-smartling-placeholder"></ph> VAST-kompatiblen Ad-Server bereitstellen und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit clientseitigen IMA SDKs Sie behalten die Kontrolle über die Videowiedergabe, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separater Videoplayer, der sich über dem Videoplayer der App befindet.

In diesem Leitfaden erfahren Sie, wie Sie das IMA SDK in eine einfache Videoplayer-App integrieren. Wenn Sie eine abgeschlossene Beispielintegration ansehen oder folgen möchten, laden Sie die einfaches Beispiel von GitHub. Wenn Sie an einem HTML5-Player mit vorintegriertem SDK interessiert sind, IMA SDK-Plug-in für Video.js

Clientseitiges IMA – Übersicht

Für die clientseitige Implementierung von IMA sind vier SDK-Hauptkomponenten erforderlich, die in diesem Leitfaden:

  • AdDisplayContainer: Ein Containerobjekt, in dem Anzeigen gerendert werden.
  • 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 den Anzeigenanfragen wird die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie Anzeigenabmessungen.
  • AdsManager: Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf die Anzeige wartet Ereignisse, die vom SDK ausgelöst werden.

Vorbereitung

Für den Start ist Folgendes erforderlich:

  • Drei leere Dateien: <ph type="x-smartling-placeholder">
      </ph>
    • index.html
    • style.css
    • ads.js
  • Python ist auf Ihrem Computer oder ein Webserver zum Testen installiert

1. Entwicklungsteam starten

Da Abhängigkeiten über das IMA SDK über dasselbe Protokoll geladen werden wie die Seite, von der es geladen wird, müssen Sie Folgendes tun: zum Testen Ihrer Anwendung einen Webserver verwenden. Der einfachste Weg, eine lokale Entwicklung zu starten ist die Verwendung des integrierten Python-Servers.

  1. Über eine Befehlszeile aus dem Verzeichnis, das führen Sie den folgenden Befehl aus: 
      python -m http.server 8000
  2. Rufe in einem Webbrowser http://localhost:8000/ auf.

Sie können auch einen beliebigen anderen Webserver verwenden, beispielsweise den Apache HTTP Server

2. Einfachen Videoplayer erstellen

Ändern Sie zuerst index.html, um ein einfaches HTML5-Videoelement zu erstellen, das in einem Wrapping enthalten ist. und eine Schaltfläche zum Auslösen der Wiedergabe. Fügen Sie außerdem die erforderlichen Tags hinzu, style.css- und ads.js-Dateien. Ändern Sie dann styles.css, um den Videoplayer responsiv für Mobilgeräte. Lösen Sie schließlich in ads.js die Videowiedergabe aus, wenn die angeklickt 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 Sie diesen Schritt ausgeführt haben, öffnen Sie index.html über Ihre Entwicklungsumgebung in Ihrem Browser. Server) sollten Sie das Videoelement sehen können und das Video sollte starten, wenn Sie auf die Schaltfläche Schaltfläche für die Wiedergabe.

3. IMA SDK importieren

Als Nächstes fügen Sie das IMA-Framework mithilfe eines Skript-Tags in index.html vor dem Tag für ads.js

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ügen Sie Ereignis-Handler hinzu, die den Aufruf folgenden Aktionen:

  • Sobald die Seite geladen ist, initialisieren Sie das IMA SDK.
  • Wenn auf die Wiedergabeschaltfläche des Videos geklickt wird, werden Anzeigen geladen (es sei denn, es wurden bereits Anzeigen geladen).
  • Wenn die Größe des Browserfensters angepasst wird, aktualisiere das Videoelement und adsManager um die Seite responsiv für Mobilgeräte zu machen,
<ph type="x-smartling-placeholder"> 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 wird vom IMA SDK ein spezielles Anzeigencontainerelement verwendet, um sowohl Anzeigen als auch anzeigenbezogenen UI-Elementen. Die Größe dieses Containers muss so angepasst werden, dass das Videoelement vom in der oberen linken Ecke. Die Höhe und Breite der in diesem Container platzierten Anzeigen werden durch den adsManager-Objekt, sodass Sie diese Werte nicht manuell festlegen müssen.

<ph type="x-smartling-placeholder">

Um dieses Anzeigencontainerelement zu implementieren, müssen Sie zuerst ein neues div-Element innerhalb der video-container-Element. Aktualisieren Sie dann das CSS, um das Element oben links zu positionieren. Ecke von video-element. Definieren Sie abschließend eine Variable für den Container im 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 eine Anzeigenanfrage stellen

Um eine Gruppe von Anzeigen anzufordern, erstellen Sie eine ima.AdsLoader-Instanz. Diese Instanz verwendet ein AdDisplayContainer-Objekt als Eingabe und kann zur Verarbeitung ima.AdsRequest-Objekte, die einer angegebenen Anzeigen-Tag-URL zugeordnet sind. Das Anzeigen-Tag, das in Dieses Beispiel enthält eine 10 Sekunden lange Pre-Roll-Anzeige. Sie können diese oder eine beliebige Anzeigen-Tag-URL mit der Methode IMA Video Suite Inspector

Als Best Practice sollten Sie nur eine Instanz von ima.AdsLoader für die gesamte Lebenszyklus einer Seite. Wenn Sie weitere Anzeigenanfragen stellen möchten, müssen Sie eine neue ima.AdsRequest erstellen Objekt, aber verwenden Sie denselben ima.AdsLoader wieder. Weitere Informationen finden Sie in der Häufig gestellte 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 die Anzeigen geladen wurden, gibt ima.AdsLoader eine Ereignis vom Typ ADS_MANAGER_LOADED. Parst das an den Callback übergebene Ereignis, um die AdsManager-Objekt. Mit AdsManager werden die Einzelanzeigen gemäß der Definition in der Antwort auf die Anzeige geladen. Tag-URL.

Beheben Sie außerdem unbedingt Fehler, die während des Ladevorgangs auftreten können. Wenn die Anzeigen nicht laden, achten Sie darauf, dass die Medienwiedergabe ohne Anzeigen fortgesetzt wird, damit die User Experience zu schaffen.

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

Um die Anzeigenwiedergabe zu starten, musst du AdsManager starten. Zur vollständigen Unterstützung von im Browser ausgeführt wird, sollte diese 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

Um sicherzustellen, dass die Größe der Anzeigen dynamisch an die Größe des Videoplayers angepasst wird, wenn der Bildschirm die Größe oder Ausrichtung ändert, muss das Ereignis zur Größenanpassung des Fensters adsManager.resize() aufrufen.

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 AdsManager-Ereignisse warten

AdsManager löst außerdem mehrere Ereignisse aus, die verarbeitet werden müssen. Diese Ereignisse werden verwendet, um Statusänderungen nachzuverfolgen, die Wiedergabe und das Pausieren des Content-Videos auszulösen und Fehler zu registrieren.

Fehlerbehebung

Der für AdsLoader erstellte Fehler-Handler kann als Fehler-Handler für den AdsManager, indem Sie einen neuen Event-Handler mit derselben Callback-Funktion hinzufügen.

ads.js 
...

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

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

...

Wiedergabe- und Pausenereignisse auslösen

Wenn AdsManager bereit ist, eine Anzeige zur Auslieferung einzufügen, wird der Ereignis vom Typ CONTENT_PAUSE_REQUESTED. Verarbeiten Sie dieses Ereignis, indem Sie eine Pause beim zugrunde liegender Videoplayer. Wenn eine Anzeige fertig ist, löst AdsManager das Ereignis Ereignis vom Typ CONTENT_RESUME_REQUESTED. Behandeln Sie dieses Ereignis, indem Sie die Wiedergabe auf der Video mit zugrunde liegenden Inhalten.

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 den zugrunde liegenden Player. Dies kann für Nutzer von Mobilgeräten verwirrend sein, denn sie erwarten, auf ein Gerät tippen zu können, Videoplayer, um die Wiedergabe zu pausieren. Um dieses Problem zu beheben, übergibt das IMA SDK alle Klicks, die nicht vom Anzeigen-Overlay bis zum AdContainer-Element verarbeitet, wo sie behandelt werden. Dies gilt nicht für lineare Anzeigen in nicht mobilen Browsern, da durch Klicken auf die Anzeige die auf den Link klicken.

Wenn Sie die Funktion „Click-to-Pause“ implementieren möchten, fügen Sie dem AdContainer einen Klick-Handler hinzu und lösen Sie die Wiedergabe aus. oder Pausen für das zugrunde liegende Video.

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 der AdsManager wird das Contentvideo pausiert, wenn eine Anzeige bereit für die Wiedergabe ist. werden im Verhalten keine nicht linearen Anzeigen berücksichtigt, bei denen der Content weiter abgespielt werden sollte, während die angezeigt wird. Zur Unterstützung nicht linearer Anzeigen warten Sie auf das AdsManager zur Ausgabe des Ereignis vom Typ LOADED. Überprüfen Sie dann, ob die Anzeige linear ist. Falls nicht, setzen Sie die Wiedergabe auf dem Videoelement.

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 und schalten diese ein. Weitere Informationen erweiterten SDK-Funktionen finden Sie in den anderen Leitfäden oder in den Beispiele auf GitHub