Aggiungere il supporto degli annunci companion

Seleziona la piattaforma: HTML5 Android iOS

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

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

Utilizzare gli annunci companion

Per utilizzare gli annunci companion:

1. Prenota gli annunci companion

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

2. Richiedi gli annunci companion

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

3. Visualizza gli 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). Alcuni vantaggi dell'utilizzo di GPT sono:

    • 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.
    • Riempimento automatico companion se manca un annuncio video.
    • Aree annuncio companion precaricate per i video player click-to-play.
    • Rendering companion automatico, inclusi HTMLResource e iFrameResource.

  • Manualmente utilizzando l'API Ad.

Utilizzare gli annunci companion con il Tag publisher di Google

Il Tag publisher di Google (GPT) automatizza la visualizzazione degli annunci HTML companion sul tuo sito. Consigliamo alla maggior parte dei publisher di utilizzare 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 in un iframe

Se soddisfi entrambi i seguenti criteri, devi includere uno script proxy aggiuntivo affinché i companion GPT vengano visualizzati correttamente:

  1. Carica l'SDK HTML5 in un iframe.
  2. Carica GPT nella pagina web principale (al di fuori 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).

Dichiarare le aree annuncio companion in HTML

Questa sezione spiega come dichiarare gli annunci companion in HTML utilizzando GPT e fornisce codice campione per diversi scenari. Per l'SDK HTML5, devi aggiungere 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 pagina HTML e dichiarare un'area annuncio. L'area annuncio dichiarata è 728x90 px. GPT tenta di riempire l'area con tutti gli annunci companion restituiti nella risposta VAST che corrispondono a queste dimensioni. 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. Vengono invece visualizzati accanto all'annuncio video master.

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 dinamica dell'area annuncio

A volte potresti non sapere quante aree annuncio hai in una pagina finché i contenuti della pagina non vengono sottoposti a rendering. Il seguente codice campione mostra come definire le aree annuncio durante il rendering della pagina. Questo esempio è identico all'Esempio 1 tranne per il fatto 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 annuncio precaricate

In alcuni casi, potrebbe essere necessario visualizzare qualcosa nell'area annuncio prima che venga richiesto l'annuncio companion. Gli annunci companion vengono in genere richiesti insieme a un annuncio video. Questa richiesta potrebbe verificarsi 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 annunci prima che venga richiesto l'annuncio companion. Per supportare questo caso d'uso, puoi visualizzare annunci web standard nell'area companion. Assicurati che gli annunci web siano indirizzati alle aree companion. Puoi indirizzare le aree companion nello stesso modo in cui indirizzeresti le aree annuncio 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.

Utilizzare gli annunci companion con l'API Ad

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

Visualizzare gli annunci companion

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

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

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

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

Visualizzare gli annunci companion flessibili

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

Immagine che mostra le impostazioni degli annunci companion di Ad Manager. Evidenzia l&#39;opzione per le dimensioni companion.

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

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