Unterstützung für Companion-Anzeigen hinzufügen

Plattform auswählen:HTML5 Android iOS

Möglicherweise möchten Sie Ihre In-Page-HTML-Anzeigenblöcke mit Video- oder Overlay-Anzeigenblöcken verknüpfen. Diese Beziehung zwischen zugehörigen Anzeigen-Slots wird als Master-Companion-Beziehung bezeichnet.

Mit dem IMA SDK können Sie nicht nur Master-Videoanzeigen und ‑Overlay-Anzeigen anfordern, sondern auch Companion-HTML-Anzeigen präsentieren. Diese Anzeigen werden in einer HTML-Umgebung ausgeliefert.

Companion-Anzeigen verwenden

So verwenden Sie Companion-Anzeigen:

1. Companion-Anzeigen buchen

Sie müssen zuerst die Companion-Anzeigen buchen, die mit Ihren Master-Anzeigen ausgeliefert werden sollen. Companion-Anzeigen können in Ad Manager getraffickt werden. Sie können bis zu sechs Companion-Anzeigen pro Master-Anzeige ausliefern. Wenn ein einzelner Käufer alle Anzeigen auf der Seite steuert, wird dies auch als Roadblocking bezeichnet.

2. Companion-Anzeigen anfordern

Standardmäßig sind Companion-Anzeigen für jede Anzeigenanfrage aktiviert.

3. Companion-Anzeigen im Displaynetzwerk

Es gibt zwei Möglichkeiten, Companion-Anzeigen zu rendern:

• Automatisch über das Google Publisher-Tag (GPT)

  Wenn Sie GPT zum Implementieren Ihrer Companion-Anzeigen verwenden, werden sie automatisch ausgeliefert, sofern auf der HTML-Seite Companion-Anzeigenflächen deklariert sind und diese Anzeigen bei der API registriert sind. Das bedeutet, dass die Div-ID in JavaScript und HTML übereinstimmen muss. GPT bietet unter anderem folgende Vorteile:

  • Erkennung von Companion-Anzeigenflächen.
  • Companion-Backfill über das Publisher-Netzwerk, wenn die VAST-Antwort weniger Companion-Anzeigen enthält, als definierte Slots auf der HTML-Seite verfügbar sind.
  • Automatisches Ausfüllen von Companion-Anzeigen, wenn eine Videoanzeige fehlt.
  • Vorab geladene Companion-Anzeigenflächen für Click-to-Play-Videoplayer.
  • Automatisierte Companion-Wiedergabe, einschließlich HTMLResource und iFrameResource.

• Manuell über die Ad API.

Companion-Anzeigen mit Google Publisher-Tag verwenden

Mit dem Google Publisher-Tag (GPT) wird die Anzeige von HTML-Companion-Anzeigen auf Ihrer Website automatisiert. Wir empfehlen den meisten Publishern, die GPT zu verwenden. Das HTML5 SDK erkennt GPT-Flächen, wenn GPT auf der Hauptwebseite (nicht in einem IFrame) geladen wird. Weitere Informationen zur Verwendung von GPT mit dem IMA SDK finden Sie in der GPT-Dokumentation.

Hinweis :Wenn Sie das Google Interactive Media Ads SDK für die Anzeigenbereitstellung verwenden, können die an den Ad-Server zurückgemeldeten Messwerte Informationen dazu enthalten, ob der Besucher mit der Seite interagiert hat, auf der die Anzeigen ausgeliefert wurden. Sie sollten diese Tatsache Ihren Besuchern offenlegen, um die in Ihrem Vertrag mit Google enthaltenen Angabepflichten für die Datenerhebung und ‑nutzung zu erfüllen.

Wenn Sie das HTML5 SDK in einem iFrame hosten

Wenn Sie beide der folgenden Kriterien erfüllen, müssen Sie ein zusätzliches Proxyskript einfügen, damit Ihre GPT-Begleiter richtig angezeigt werden:

1. Laden Sie das HTML5 SDK in einem iFrame.
2. Laden Sie GPT auf der Hauptwebseite (außerhalb des iFrames).

Damit Ihre Begleiter in diesem Szenario angezeigt werden, müssen Sie das GPT-Proxyscript vor dem Laden des SDK laden:

<script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>

Was Sie unbedingt beachten sollten:

• Im IFrame, in dem das SDK geladen wird, darf kein GPT geladen werden.
• GPT muss auf der obersten Seite und nicht in einem anderen iFrame geladen werden.
• Das Proxy-Script muss im selben Frame wie GPT geladen werden, also auf der Hauptseite.

Companion-Anzeigenflächen in HTML deklarieren

In diesem Abschnitt wird erläutert, wie Sie Companion-Anzeigen in HTML mit GPT deklarieren. Außerdem finden Sie Beispielcode für verschiedene Szenarien. Für das HTML5 SDK müssen Sie Ihrer HTML-Seite JavaScript hinzufügen und die Companion-Anzeigen-Slots deklarieren.

Hinweis :Achten Sie in jedem der folgenden Beispiele darauf, dass Sie im googletag.defineSlot-Methodenaufruf (im <head>- oder <body>-Tag, je nach verwendetem Beispiel) eine gültige network und unit-path angeben.

• Beispiel 1: Einfache Implementierung von Anzeigen-Slots
• Beispiel 2: Implementierung dynamischer Anzeigenblöcke
• Beispiel 3: Vorab geladene Anzeigenflächen

Beispiel 1: Einfache Implementierung von Anzeigen-Slots

Im folgenden Beispielcode sehen Sie, wie Sie die gpt.js-Datei in Ihre HTML-Seite einfügen und einen Anzeigen-Slot deklarieren. Die deklarierte Anzeigenfläche hat die Größe 728 × 90 Pixel. Das GPT versucht, den Slot mit Companion-Anzeigen zu füllen, die in der VAST-Antwort zurückgegeben werden und dieser Größe entsprechen. Nachdem die Anzeigen-Slots deklariert wurden, können sie mit der Funktion googletag.display() überall auf der Seite gerendert werden, wo sie aufgerufen wird. Da es sich bei den Slots um Companion-Slots handelt, werden Anzeigen nicht sofort ausgeliefert. Stattdessen werden sie neben der Master-Videoanzeige eingeblendet.

Hier ein Beispiel für die Implementierung:

<html>
  <head>
    <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
    <!--<script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>-->
    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>

    <!-- Register your companion slots -->
    <script>
       window.googletag = window.googletag || { cmd: [] };

       googletag.cmd.push(function() {
         // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
         googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
             .addService(googletag.companionAds())
             .addService(googletag.pubads());
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
    </script>
  </head>

  <body>
    <!-- BODY part -->
    <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv" style="width:728px; height:90px;">
      <script>
         // Using the command queue to enable asynchronous loading.
         // The unit does not actually display now - it displays when
         // the video player is displaying the ads.
         googletag.cmd.push(function() { googletag.display('companionDiv'); });
      </script>
    </div>
  <body>
</html>

Jetzt ausprobieren

Eine funktionierende Implementierung finden Sie im folgenden Codepen.

CodePen

Beispiel 2: Implementierung dynamischer Anzeigen-Slots

Manchmal wissen Sie erst nach dem Rendern der Seiteninhalte, wie viele Anzeigenflächen Sie auf einer Seite haben. Im folgenden Beispielcode sehen Sie, wie Anzeigen-Slots während des Renderns der Seite definiert werden. Dieses Beispiel ist mit Beispiel 1 identisch, mit dem Unterschied, dass die Anzeigen-Slots dort registriert werden, wo sie tatsächlich ausgeliefert werden.

Hinweis :Wenn der Videoplayer die Anzeigen einblenden möchte, fragt er die Slots an. Achten Sie darauf, dass die Slots definiert sind, bevor der Player die Anzeigen präsentiert.

<html>
  <head>
    <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
    <!-- <script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script> -->
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(function() {
        googletag.companionAds().setRefreshUnfilledSlots(true);
        googletag.pubads().enableVideoAds();
        googletag.enableServices();
      });
    </script>
  </head>

  <body>
    <!-- BODY part -->
    <!-- Declare a div where you want the companion to appear. Use
        googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv" style="width:728px; height:90px;">
      <script>
        // Using the command queue to enable asynchronous loading.
        // The unit does not actually display now - it displays when
        // the video player is displaying the ads.
        googletag.cmd.push(function() {
          // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
          googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
              .addService(googletag.companionAds())
              .addService(googletag.pubads());
          googletag.display('companionDiv');
        });
      </script>
    </div>
  <body>
</html>

Jetzt ausprobieren

Im folgenden Code sehen Sie eine funktionierende Implementierung.

Beispiel 3: Vorab geladene Anzeigen-Slots

In bestimmten Fällen müssen Sie möglicherweise etwas auf der Anzeigenfläche präsentieren, bevor die Companion-Anzeige angefordert wird. Companion-Anzeigen werden in der Regel zusammen mit einer Videoanzeige angefordert. Diese Anfrage kann nach dem Laden der Seite erfolgen. Eine Companion-Anzeige wird beispielsweise erst geladen, nachdem der Nutzer auf ein Click-to-Play-Video geklickt hat. In diesem Fall müssen Sie eine reguläre Anzeige anfordern können, um die Anzeigenfläche zu füllen, bevor die Companion-Anzeige angefordert wird. Für diesen Anwendungsfall können Sie Standard-Webanzeigen im Companion-Slot einblenden. Achten Sie darauf, dass die Webanzeigen auf die Companion-Anzeigenflächen ausgerichtet sind. Sie können die Companion-Anzeigenflächen auf dieselbe Weise ausrichten wie Standard-Anzeigenflächen im Web.

Hinweis :Der folgende Beispielcode ist mit Ausnahme des fett gedruckten Abschnitts identisch mit dem für Beispiel 1. In diesem Fall geben Sie das Anzeigennetzwerk und den Anzeigenblockpfad Ihrer Preload-Anzeige anstelle Ihres Video-Anzeigenblocks an.

Hier ein Beispiel für die beschriebene Implementierung:

<html>
  <head>
    ...
    <!-- Register your companion slots -->
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(function() {
        // Supply YOUR_PRELOAD_NETWORK and YOUR_PRELOAD_UNIT_PATH.
        googletag.defineSlot('/YOUR_PRELOAD_NETWORK/YOUR_PRELOAD_UNIT_PATH', [728, 90], 'companionDiv')
            .addService(googletag.companionAds())
            .addService(googletag.pubads());
        googletag.companionAds().setRefreshUnfilledSlots(true);
        googletag.pubads().enableVideoAds();
        googletag.enableServices();
      });
    </script>
  </head>
  ...
</html>

Jetzt ausprobieren

Im folgenden Code-Pen sehen Sie eine funktionierende Implementierung.

Companion-Anzeigen mit der Ad API verwenden

In diesem Abschnitt wird beschrieben, wie Sie Companion-Anzeigen mit der Ad API präsentieren.

Companion-Anzeigen im Displaynetzwerk

Um Companion-Anzeigen zu präsentieren, müssen Sie zuerst über eines der AdEvent-Ereignisse, die von AdsManager gesendet werden, eine Referenz zu einem Ad-Objekt abrufen. Wir empfehlen, das AdEvent.STARTED-Ereignis zu verwenden, da die Companion-Anzeigen gleichzeitig mit der Master-Anzeige ausgeliefert werden sollten.

Verwenden Sie dieses Ad-Objekt als Nächstes, um getCompanionAds() aufzurufen und ein Array von CompanionAd-Objekten abzurufen. Hier haben Sie die Möglichkeit, CompanionAdSelectionSettings anzugeben. Damit können Sie Filter für Companion-Anzeigen nach Creative-Typ, prozentualer Übereinstimmung, Ressourcentyp und Größenkriterien festlegen. Weitere Informationen zu diesen Einstellungen finden Sie in der IMA-Dokumentation zur CompanionAdSelectionSettings API.

Die von getCompanionAds zurückgegebenen CompanionAd-Objekte können jetzt verwendet werden, um die Companion-Anzeigen auf der Seite zu präsentieren. Dabei sind folgende Richtlinien zu beachten:

1. Erstellen Sie auf der Seite einen Companion-Anzeigenblock <div> in der erforderlichen Größe.
2. Rufen Sie in Ihrem Event-Handler für das Ereignis STARTED das Objekt Ad ab, indem Sie getAd() aufrufen.
3. Verwenden Sie getCompanionAds(), um eine Liste von Companion-Anzeigen zu erhalten, die sowohl der Größe der Companion-Anzeigenfläche als auch CompanionAdSelectionSettings entsprechen und dieselbe Sequenznummer wie das Master-Creative haben. Creatives ohne Attribut für die Sequenz werden so behandelt, als hätten sie die Sequenznummer 0.
4. Rufen Sie den Inhalt aus einer CompanionAd-Instanz ab und legen Sie ihn als innerHTML des <div> des Anzeigen-Slots fest.

Beispielcode

<!--Set a companion ad div in html page. -->
<div id="companion-ad-300-250" width="300" height="250"></div>

<script>

  // Listen to the STARTED event.
  adsManager.addEventListener(
    google.ima.AdEvent.Type.STARTED,
    onAdEvent);

  function onAdEvent(adEvent) {
    switch (adEvent.type) {
      case google.ima.AdEvent.Type.STARTED:
        // Get the ad from the event.
        var ad = adEvent.getAd();
        var selectionCriteria = new google.ima.CompanionAdSelectionSettings();
        selectionCriteria.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
        selectionCriteria.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
        selectionCriteria.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.IGNORE;
        // Get a list of companion ads for an ad slot size and CompanionAdSelectionSettings
        var companionAds = ad.getCompanionAds(300, 250, selectionCriteria);
        var companionAd = companionAds[0];
        // Get HTML content from the companion ad.
        var content = companionAd.getContent();
        // Write the content to the companion ad slot.
        var div = document.getElementById('companion-ad-300-250');
        div.innerHTML = content;
        break;
    }
  }
</script>

Companion-Anzeigen mit flüssigem Layout ausliefern

Das IMA SDK unterstützt jetzt flexible Companion-Anzeigen. Die Größe dieser Companion-Anzeigen kann an die Größe der Anzeigenfläche angepasst werden. Sie füllen die gesamte Breite des übergeordneten Div-Elements aus und passen dann ihre Höhe an den Inhalt des Companion-Elements an. Sie werden in Ad Manager mit der Fluid-Companion-Größe festgelegt. Die folgende Abbildung zeigt, wo Sie diesen Wert festlegen können.

GPT-Begleiter für flüssige Inhalte

Wenn Sie GPT-Begleiter verwenden, können Sie einen dynamischen Companion-Slot deklarieren, indem Sie den zweiten Parameter der Methode defineSlot() aktualisieren.

<!-- Register your companion slots -->
<script>
  googletag.cmd.push(function() {
    // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
    googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', ['fluid'], 'companionDiv')
        .addService(googletag.companionAds())
        .addService(googletag.pubads());
    googletag.companionAds().setRefreshUnfilledSlots(true);
    googletag.pubads().enableVideoAds();
    googletag.enableServices();
  });
</script>

Begleitende Fluid-Anzeigen-APIs

Wenn Sie die Ad API für Companion-Anzeigen verwenden, können Sie einen responsiven Companion-Slot deklarieren, indem Sie google.ima.CompanionAdSelectionSettings.SizeCriteria auf den Wert SELECT_FLUID aktualisieren.

<script>

  ...
    // Get the ad from the event.
    var ad = adEvent.getAd();
    var selectionCriteria = new google.ima.CompanionAdSelectionSettings();
    selectionCriteria.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
    selectionCriteria.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
    selectionCriteria.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.SELECT_FLUID;
    // Get a list of companion ads for an ad slot size and CompanionAdSelectionSettings
    // Note: Companion width and height are irrelevant when fluid size is used.
    var companionAds = ad.getCompanionAds(0, 0, selectionCriteria);
    var companionAd = companionAds[0];
  ...
    }
  }
</script>