Aggiungere il supporto degli annunci companion

Seleziona la piattaforma: HTML5 Android iOS

Potresti voler associare le aree annunci HTML in-page alle aree annunci video o in overlay. Questa relazione tra aree annuncio associate è chiamata relazione principale-companion.

Oltre a richiedere annunci video e overlay principali, puoi utilizzare l'SDK IMA per visualizzare annunci HTML companion. Questi annunci vengono visualizzati in un ambiente HTML

Utilizza gli annunci companion

Per utilizzare gli annunci companion, segui questi passaggi:

1. Prenota gli annunci companion

Devi prima prenotare gli annunci companion che vuoi mostrare con gli annunci principali. Gli annunci companion possono essere gestiti in Ad Manager. Puoi pubblicare fino a sei annunci companion per annuncio master. Questa tecnica, in cui un singolo acquirente controlla tutti gli annunci della pagina, è nota anche come roadblocking.

2. Richiedi gli annunci companion

Per impostazione predefinita, gli annunci companion sono attivati per ogni richiesta di annuncio.

3. Visualizza annunci companion

Esistono due modi per eseguire il rendering degli annunci companion:

  • Automaticamente utilizzando il Tag publisher di Google (GPT).

    Se utilizzi GPT per implementare gli annunci companion, questi vengono visualizzati automaticamente, a condizione che nella pagina HTML siano dichiarate aree annuncio companion e che questi annunci siano registrati con l'API (ovvero l'ID div in JavaScript e HTML deve corrispondere). Ecco alcuni vantaggi dell'utilizzo di GPT:

    • Rilevamento dell'area annuncio companion.
    • Backfill companion dalla rete del publisher, se la risposta VAST contiene meno annunci companion rispetto alle aree definite nella pagina HTML.
    • Compilazione automatica del companion se manca un annuncio video.
    • Aree annuncio companion precaricate per i video player click-to-play.
    • Rendering automatico dei companion, inclusi HTMLResource e iFrameResource.

  • Manualmente utilizzando l'API Ad.

Utilizza gli annunci companion con Tag publisher di Google

Il Tag publisher di Google (GPT) automatizza la visualizzazione degli annunci companion HTML sul tuo sito. Consigliamo alla maggior parte dei publisher di utilizzare i GPT. L'SDK HTML5 riconosce le aree GPT se GPT viene caricato nella pagina web principale (non in un iframe). Puoi trovare informazioni più dettagliate sull'utilizzo di GPT con l'SDK IMA nella documentazione di GPT.

Se ospiti l'SDK HTML5 all'interno di un iframe

Se soddisfi entrambi i seguenti criteri, devi includere uno script proxy aggiuntivo per visualizzare correttamente gli annunci companion GPT:

  1. Carica l'SDK HTML5 in un iframe.
  2. Carica GPT sulla pagina web principale (all'esterno dell'iframe).

Per visualizzare i companion in questo scenario, devi caricare lo script proxy GPT prima di caricare l'SDK:

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

Importante.

  • Non deve essere caricato alcun GPT all'interno dell'iframe che carica l'SDK.
  • GPT deve essere caricato nella pagina principale, non in un altro iframe.
  • Lo script proxy deve essere caricato nello stesso frame di GPT (ovvero nella pagina principale).

Dichiara le aree annuncio companion in HTML

Questa sezione spiega come dichiarare gli annunci companion in HTML utilizzando GPT e fornisce un codice campione per diversi scenari. Per l'SDK HTML5, devi aggiungere del codice JavaScript alla pagina HTML e dichiarare le aree annuncio companion.

Esempio 1: implementazione di base dell'area annuncio

Il seguente codice campione mostra come includere il file gpt.js nella tua pagina HTML e dichiarare un'area annuncio. L'area annuncio dichiarata è 728 x 90 px. GPT tenta di riempire l'area annuncio con gli annunci companion restituiti nella risposta VAST che corrispondono a questa dimensione. Dopo aver dichiarato le aree annuncio, la funzione googletag.display() può eseguirne il rendering ovunque venga chiamata nella pagina. Poiché le aree sono aree companion, gli annunci non vengono visualizzati immediatamente. ma vengono visualizzati accanto all'annuncio video principale.

Ecco un esempio di implementazione:

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

Prova

Puoi vedere il seguente codepen per un'implementazione funzionante.

Esempio 2: implementazione di un'area annuncio dinamica

A volte potresti non sapere quante aree annuncio hai su una pagina finché non viene eseguito il rendering dei contenuti della pagina. Il seguente codice campione mostra come definire le aree annuncio durante il rendering della pagina. Questo esempio è identico all'Esempio 1, con la differenza che registra le aree annuncio dove vengono effettivamente visualizzate.

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

Prova

Puoi vedere il seguente codice per un'implementazione funzionante.

Esempio 3: aree annunci precaricate

In alcuni casi, potrebbe essere necessario visualizzare qualcosa nell'area annuncio prima che venga richiesto l'annuncio companion. Gli annunci companion vengono solitamente richiesti insieme a un annuncio video. Questa richiesta potrebbe essere eseguita dopo il caricamento della pagina. Ad esempio, un annuncio companion potrebbe essere caricato solo dopo che l'utente ha fatto clic su un video click-to-play. In questo caso, devi avere la possibilità di richiedere un annuncio normale per riempire l'area annuncio prima che venga richiesto l'annuncio companion. Per supportare questo caso d'uso, puoi mostrare annunci web standard nell'area companion. Assicurati che gli annunci web siano indirizzati alle aree companion. Puoi scegliere come target le aree companion nello stesso modo in cui sceglieresti come target le aree annunci web standard.

Ecco un esempio dell'implementazione appena descritta:

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

Prova

Puoi vedere il seguente CodePen per un'implementazione funzionante.

Utilizza gli annunci companion con l'API Ad

Questa sezione descrive come visualizzare gli annunci companion utilizzando l'API Ad.

Visualizza annunci companion

Per visualizzare gli annunci companion, devi prima ottenere un riferimento a un oggetto Ad tramite uno qualsiasi degli eventi AdEvent inviati da AdsManager. Ti consigliamo di utilizzare l'evento AdEvent.STARTED, poiché la visualizzazione degli annunci companion deve coincidere con quella dell'annuncio principale.

Successivamente, utilizza questo oggetto Ad per chiamare getCompanionAds() e ottenere un array di oggetti CompanionAd. Qui hai la possibilità di specificare CompanionAdSelectionSettings, che ti consente di impostare filtri sugli annunci companion per i criteri di tipo di creatività, percentuale di corrispondenza approssimativa, tipo di risorsa e dimensioni. Per saperne di più su queste impostazioni, consulta la documentazione dell'API IMA CompanionAdSelectionSettings.

Gli oggetti CompanionAd restituiti da getCompanionAds ora possono essere utilizzati per visualizzare gli annunci companion sulla pagina utilizzando queste linee guida:

  1. Crea un'area annunci companion <div> delle dimensioni richieste nella pagina.
  2. Nel gestore di eventi per l'evento STARTED, recupera l'oggetto Ad chiamando getAd().
  3. Utilizza getCompanionAds() per ottenere un elenco di annunci companion che corrispondono sia alle dimensioni dell'area annuncio companion sia a CompanionAdSelectionSettings e hanno lo stesso numero di sequenza della creatività principale. Le creatività con un attributo di sequenza mancante vengono trattate come se avessero il numero di sequenza 0.
  4. Recupera i contenuti da un'istanza CompanionAd e impostali come HTML interno del <div> dell'area annuncio.

Codice campione

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

Visualizza annunci companion fluidi

IMA ora supporta gli annunci companion flessibili. Questi annunci companion possono essere ridimensionati per adattarsi alle dimensioni dell'area annuncio. Riempiono il 100% della larghezza del div principale, quindi ridimensionano l'altezza per adattarla ai contenuti del companion. Vengono impostati utilizzando la dimensione companion Fluid in Ad Manager. Consulta l'immagine seguente per sapere dove impostare questo valore.

Immagine che mostra le impostazioni degli annunci companion di Ad Manager. Evidenzia l'opzione delle dimensioni companion.

Companion fluidi GPT

Quando utilizzi i companion GPT, puoi dichiarare un'area companion flessibile aggiornando il secondo parametro del metodo defineSlot().

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

Annunci companion fluidi dell'API Ad

Quando utilizzi l'API Ad per gli annunci companion, puoi dichiarare un'area companion flessibile aggiornando google.ima.CompanionAdSelectionSettings.SizeCriteria al valore SELECT_FLUID.

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