Aggiungere il supporto degli annunci companion

Seleziona piattaforma: HTML5 Android iOS

Potresti voler associare le aree riservate agli annunci HTML in pagina alle aree riservate agli annunci video o overlay. Questa relazione tra gli spazi pubblicitari associati è definita relazione principale-companion.

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 gli annunci companion

Per utilizzare gli annunci companion:

1. Prenotare gli annunci companion

Devi prima prenotare gli annunci companion che vuoi visualizzare con i tuoi annunci principali. Gli annunci companion possono essere gestiti in Ad Manager. Puoi pubblicare fino a sei annunci companion per ogni annuncio principale. Questa tecnica, in cui un unico acquirente controlla tutti gli annunci sulla pagina, è nota anche come roadblocking.

2. Richiedere gli annunci companion

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

3. Annunci display 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 purché siano dichiarate aree annuncio companion nella pagina HTML e 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 agli spazi definiti nella pagina HTML.
  • Il riempimento automatico del companion se manca un annuncio video.
  • Aree annuncio companion precaricate per i video player click-to-play.
  • Rendering automatico delle companion, 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 companion HTML sul tuo sito. Consigliamo alla maggior parte dei publisher di utilizzare GPT. L'SDK HTML5 riconosce gli slot 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.

Nota :quando utilizzi l'SDK Google Interactive Media Ads per la pubblicazione di annunci, le metriche riportate all'ad server possono includere informazioni sull'interazione del visitatore con la pagina in cui sono stati pubblicati gli annunci. Devi comunicarlo ai tuoi visitatori per rispettare il requisito di divulgazione della raccolta e dell'utilizzo dei dati previsto dal tuo contratto con Google.

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

Se soddisfi entrambi i seguenti criteri, devi includere uno script proxy aggiuntivo affinché i tuoi 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 tuoi 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 gli spazi pubblicitari companion in HTML

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

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

• Esempio 1: implementazione di base dell'area annuncio
• Esempio 2: implementazione degli spazi pubblicitari dinamici
• Esempio 3: spazi pubblicitari precaricati

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 uno spazio pubblicitario. L'area annuncio dichiarata è 728 x 90 px. GPT tenta di riempire lo spazio con gli annunci companion restituiti nella risposta VAST che corrispondono a queste dimensioni. Una volta dichiarati gli spazi pubblicitari, la funzione googletag.display() può eseguirne il rendering ovunque venga chiamata nella pagina. Poiché gli slot sono slot 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

Per un'implementazione funzionante, puoi consultare il seguente Codepen.

Esempio 2: implementazione di aree annuncio dinamiche

A volte potresti non sapere quanti spazi pubblicitari hai in una pagina finché non vengono visualizzati i contenuti della pagina. Il seguente esempio di codice mostra come definire gli spazi pubblicitari durante il rendering della pagina. Questo esempio è identico all'esempio 1, tranne per il fatto che registra gli spazi pubblicitari in cui vengono effettivamente visualizzati.

Nota: quando il video player sta per mostrare gli annunci, chiede gli slot. Assicurati che gli slot siano definiti 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, puoi visualizzare il seguente codice.

Esempio 3: aree annuncio precaricate

In alcuni casi, potrebbe essere necessario visualizzare qualcosa nello spazio pubblicitario prima che venga richiesto l'annuncio companion. Gli annunci companion vengono solitamente 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 avere la possibilità di richiedere un annuncio normale per riempire lo spazio pubblicitario prima che venga richiesto l'annuncio companion. Per supportare questo caso d'uso, puoi mostrare annunci web standard nello spazio complementare. Assicurati che gli annunci web siano indirizzati agli spazi companion. Puoi scegliere come target gli spazi pubblicitari companion nello stesso modo in cui sceglieresti come target gli spazi pubblicitari 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, fornisci il percorso dell'unità e della rete pubblicitaria del tuo annuncio di precaricamento anziché quello dell'unità pubblicitaria video.

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

Per un'implementazione funzionante, puoi consultare il seguente codice.

Utilizzare gli annunci companion con l'API Ad

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

Annunci display 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 la visualizzazione 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 complementari per tipo di creatività, percentuale di corrispondenza approssimativa, tipo di risorsa e criteri di dimensione. 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 mostrare gli annunci companion sulla pagina seguendo queste linee guida:

1. Crea un'area annuncio 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 dello spazio pubblicitario 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 di <div> dello spazio pubblicitario.

Codice di esempio

<!--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 annunci companion fluidi

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

Companion fluidi GPT

Quando utilizzi i companion GPT, puoi dichiarare uno spazio companion fluido 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>

Componenti fluidi dell'API Ad

Quando utilizzi l'API Ad per gli annunci companion, puoi dichiarare uno slot companion fluido 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>