Questa pagina è stata tradotta dall'API Cloud Translation.

Annunci companion

Ti consigliamo di associare le tue aree annuncio HTML in-page alle aree annuncio video o overlay. Questa relazione tra aree annuncio associate è denominata relazione principale-associato.

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

Utilizzare annunci companion

Per utilizzare gli annunci companion, procedi nel seguente modo:

1. Prenota gli annunci companion

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

2. Richiedere gli annunci companion

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

3. Annunci companion display

Esistono due modi per eseguire il rendering di annunci companion:

Automaticamente con 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 state dichiarate aree annuncio companion e che questi annunci siano registrati nell'API (ovvero, l'ID div in JavaScript e nell'HTML devono corrispondere). Ecco alcuni vantaggi dell'utilizzo dei tag GPT:
- Rilevamento dell'area companion
- Backfill companion dalla rete del publisher, se la risposta VAST contiene meno annunci companion rispetto alle aree definite nella pagina HTML
- Compilazione automatica companion se manca un annuncio video
- Aree annunci companion precaricate per i video player click-to-play
- Rendering companion automatico, inclusi HTMLResource e iFrameResource
Utilizzare manualmente l'API Ad.

Utilizzare 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 degli editori di utilizzare GPT. L'SDK HTML5 riconosce gli slot GPT se il GPT viene caricato nella pagina web principale (non in un iframe). Puoi trovare informazioni più dettagliate sull'uso di GPT con l'SDK IMA nella documentazione relativa a GPT.

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

Se soddisfi entrambi i criteri riportati di seguito, devi includere uno script proxy aggiuntivo affinché le creatività companion GPT vengano visualizzate correttamente:

Carica l'SDK HTML5 in un iframe.
Carica GPT sulla pagina web principale (al di fuori dell'IFrame).

Per visualizzare le creatività 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 dovrebbe essere caricato 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 del tag 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 codice di esempio per diversi scenari. Per l'SDK HTML5, devi aggiungere codice JavaScript alla pagina HTML e dichiarare le aree annuncio companion.

Nota: in ognuno degli esempi seguenti, assicurati di fornire un valore network e unit-path valido nella chiamata al metodo googletag.defineSlot (che si trova nel tag <head> o <body>, a seconda dell'esempio effettivo che stai utilizzando).

Esempio 1: implementazione di base dell'area annuncio
Esempio 2: implementazione di aree annuncio dinamiche
Esempio 3: aree annuncio precaricate

Esempio 1: implementazione di base dell'area annuncio

Il seguente codice di esempio mostra come includere il file gpt.js nella pagina HTML e dichiarare un'area annuncio. L'area annuncio dichiarata è di 728 x 90 px. GPT tenta di riempire l'area con qualsiasi annuncio companion restituito nella risposta VAST che corrisponda a questa dimensione. Una volta dichiarate le aree annuncio, la funzione googletag.display() può eseguirne il rendering ogni volta che viene richiamata nella pagina. Poiché le aree sono companion, gli annunci non vengono visualizzati immediatamente. Vengono invece visualizzati accanto all'annuncio video principale.

Di seguito è riportato 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

Per un'implementazione funzionante, puoi visualizzare il seguente codepen.

Esempio 2: implementazione dell'area annuncio dinamica

A volte potresti non sapere quante aree annuncio sono presenti in una pagina fino a quando non viene eseguito il rendering dei contenuti della pagina. Il seguente codice di esempio mostra come definire le aree annuncio durante il rendering della pagina. Questo esempio è identico all'Esempio 1, ad eccezione del fatto che registra le aree annuncio in cui vengono effettivamente visualizzate.

Nota: quando il video player sta per mostrare gli annunci, chiede gli slot. Assicurati che le aree annuncio siano definite prima che il player mostri gli annunci.

 <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

Per un'implementazione funzionante, vedi il codice riportato di seguito.

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 generalmente richiesti insieme a un annuncio video. Questa richiesta potrebbe verificarsi dopo il caricamento della pagina. Ad esempio, un annuncio companion può essere caricato solo dopo che l'utente fa clic su un video click-to-play. In questo caso, devi poter richiedere un annuncio normale per riempire l'area annuncio 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 abbiano come target le aree companion. Puoi scegliere come target le aree companion come faresti per le aree annuncio web standard.

Nota: il seguente codice campione è esattamente uguale a quello fornito per l'esempio 1, ad eccezione della sezione in grassetto. In questo caso, devi fornire la rete pubblicitaria e il percorso dell'unità dell'annuncio precaricato al posto dell'unità pubblicitaria video.

Di seguito è riportato 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 penna di codice per un'implementazione funzionante.

Utilizzare gli annunci companion con l'API Ad

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

Annunci companion display

Per visualizzare gli annunci companion, ottieni prima un riferimento a un oggetto Ad tramite uno degli eventi AdEvent inviati da AdsManager. Ti consigliamo di utilizzare l'evento AdEvent.STARTED, in quanto la visualizzazione degli annunci companion dovrebbe coincidere con la visualizzazione dell'annuncio principale.

Quindi, utilizza questo oggetto Ad per chiamare getCompanionAds() e ottenere un array di oggetti CompanionAd. Qui hai la possibilità di specificare CompanionAdSelectionSettings, in modo da poter impostare filtri sugli annunci companion per tipo di creatività, percentuale quasi di idoneità, tipo di risorsa e criteri relativi alle dimensioni. Per ulteriori informazioni su queste impostazioni, consulta la documentazione dell'API HTML5.

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

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

Annunci companion display fluidi

Ora l'IMA 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 per adattarla ai contenuti dell'annuncio companion. Vengono impostate utilizzando la dimensione companion Fluid in Ad Manager. Vedi l'immagine di seguito per sapere dove impostare questo valore.

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

Companion flessibili in GPT

Quando utilizzi companion GPT, puoi dichiarare un'area companion fluida 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 annuncio

Quando utilizzi l'API Ad per gli annunci companion, puoi dichiarare un'area companion fluida 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>