Adicionar suporte a anúncios complementares

Selecione a plataforma: HTML5 Android iOS

Talvez você queira associar seus espaços de anúncio HTML na página a espaços de anúncio em vídeo ou de sobreposição. Essa relação entre os espaços de anúncio associados é chamada de relação principal-complementar.

Além de solicitar anúncios principais em vídeo e sobrepostos, você pode usar o SDK do IMA para exibir anúncios HTML complementares. Esses anúncios são exibidos em um ambiente HTML.

Usar anúncios complementares

Para usar anúncios complementares, siga estas etapas:

1. Reservar anúncios complementares

Primeiro, reserve os anúncios complementares que você quer mostrar com seus anúncios principais. Os anúncios complementares podem ser programados no Ad Manager. É possível veicular até seis anúncios complementares por anúncio principal. Essa técnica, em que um único comprador controla todos os anúncios na página, também é conhecida como roadblocking.

2. Solicitar anúncios complementares

Por padrão, os anúncios complementares são ativados para cada solicitação de anúncio.

3. Anúncios complementares de display

Há duas maneiras de renderizar anúncios complementares:

• Automaticamente usando a Tag do editor do Google (GPT).

  Se você estiver usando a GPT para implementar seus anúncios complementares, eles serão mostrados automaticamente desde que haja espaços de anúncio complementar declarados na página HTML e que esses anúncios estejam registrados na API (ou seja, o ID da div no JavaScript e no HTML precisa corresponder). Alguns benefícios de usar a GPT:

  • Conhecimento do espaço dos anúncios complementares.
  • Preenchimento complementar da rede do editor se a resposta VAST tiver menos anúncios complementares do que os locais definidos na página HTML.
  • Preenchimento automático complementar se um anúncio em vídeo estiver faltando.
  • Espaços de anúncios complementares pré-carregados para players de vídeo "clicar para reproduzir".
  • Renderização automática de complementos, incluindo HTMLResource e iFrameResource.

• Manualmente usando a API Ads.

Usar anúncios complementares com a Tag do editor do Google

A Tag do editor do Google (GPT) automatiza a exibição de anúncios complementares em HTML no seu site. Recomendamos que a maioria dos editores use a GPT. O SDK HTML5 reconhece slots da GPT se ela for carregada na página da Web principal (não em um IFrame). Encontre informações mais detalhadas sobre como usar a GPT com o SDK IMA na documentação da GPT.

Observação: quando você usa o SDK Interactive Media Ads do Google para veiculação de anúncios, as métricas informadas ao servidor de anúncios podem incluir se o visitante interagiu com a página em que os anúncios foram veiculados. Você precisa informar isso aos visitantes para cumprir o requisito de divulgação sobre coleta e uso de dados do seu contrato com o Google.

Se você hospedar o SDK HTML5 em um IFrame

Se você atender aos dois critérios a seguir, inclua um script de proxy extra para que os complementos da GPT sejam exibidos corretamente:

1. Carregue o SDK HTML5 em um iframe.
2. Carregue a GPT na página da Web principal (fora do iframe).

Para que os complementos apareçam nesse cenário, carregue o script de proxy do GPT antes de carregar o SDK:

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

Outros pontos a serem considerados:

• Não pode haver uma GPT carregada dentro do iframe que carrega o SDK.
• A GPT precisa ser carregada na página principal, não em outro iframe.
• O script de proxy precisa ser carregado no mesmo frame que a GPT, ou seja, na página principal.

Declarar espaços para anúncios complementares em HTML

Esta seção explica como declarar anúncios complementares em HTML usando a GPT e fornece exemplos de código para diferentes cenários. Para o SDK HTML5, você precisa adicionar um pouco de JavaScript à sua página HTML e declarar os slots de anúncios complementares.

Observação: em cada um dos exemplos a seguir, forneça um network e um unit-path válidos na chamada do método googletag.defineSlot (localizada na tag <head> ou <body>, dependendo do exemplo que você está usando).

• Exemplo 1: implementação básica de um slot de anúncio
• Exemplo 2: implementação de um slot de anúncio dinâmico
• Exemplo 3: espaços de anúncios pré-carregados

Exemplo 1: implementação básica de locais de anúncios

O exemplo de código a seguir mostra como incluir o arquivo gpt.js na sua página HTML e declarar um slot de anúncio. O espaço de anúncio declarado é de 728 x 90 px. A GPT tenta preencher o slot com os anúncios complementares retornados na resposta VAST que correspondem a esse tamanho. Depois que os espaços de anúncio são declarados, a função googletag.display() pode renderizá-los em qualquer lugar da página em que for chamada. Como os espaços são complementares, os anúncios não são exibidos imediatamente. Em vez disso, eles aparecem ao lado do anúncio em vídeo principal.

Confira um exemplo de implementação:

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

Faça um teste

Confira o seguinte codepen para uma implementação funcional.

Exemplo 2: implementação dinâmica de locais de anúncios

Às vezes, você não sabe quantos espaços de anúncio tem em uma página até que o conteúdo dela seja renderizado. O exemplo de código a seguir mostra como definir slots de anúncio enquanto a página é renderizada. Este exemplo é idêntico ao Exemplo 1, exceto que ele registra os slots de anúncio onde eles são realmente exibidos.

Observação: quando o player de vídeo está prestes a mostrar os anúncios, ele pede os slots. Verifique se os slots estão definidos antes que o player mostre os anúncios.

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

Faça um teste

Confira o código a seguir para uma implementação funcional.

Exemplo 3: locais de anúncio carregados previamente

Em alguns casos, talvez seja necessário mostrar algo no slot de anúncio antes que o anúncio complementar seja solicitado. Os anúncios complementares geralmente são solicitados junto com um anúncio em vídeo. Essa solicitação pode ocorrer depois que a página é carregada. Por exemplo, um anúncio complementar pode ser carregado somente depois que o usuário clica em um vídeo "clicar para reproduzir". Nesse caso, você precisa ter a capacidade de solicitar um anúncio normal para preencher o espaço antes que o complementar seja solicitado. Para apoiar esse caso de uso, você pode mostrar anúncios da Web padrão no espaço complementar. Verifique se os anúncios da Web estão segmentados para os espaços complementares. É possível segmentar os espaços complementares da mesma forma que os espaços de anúncios da Web padrão.

Observação: o exemplo de código a seguir é exatamente igual ao fornecido para o exemplo 1, exceto pela seção em negrito. Nesse caso, você fornece o caminho da rede de publicidade e do bloco do anúncio de pré-carregamento em vez do bloco de anúncios em vídeo.

Confira um exemplo da implementação descrita acima:

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

Faça um teste

Confira o seguinte CodePen para uma implementação funcional.

Usar anúncios complementares com a API Ad

Nesta seção, descrevemos como mostrar anúncios complementares usando a API Ad.

Anúncios complementares de display

Para mostrar anúncios complementares, primeiro receba uma referência a um objeto Ad usando qualquer um dos eventos AdEvent enviados do AdsManager. Recomendamos usar o evento AdEvent.STARTED, já que a exibição de anúncios complementares deve coincidir com a exibição do anúncio principal.

Em seguida, use esse objeto Ad para chamar getCompanionAds() e receber uma matriz de objetos CompanionAd. Aqui, você pode especificar CompanionAdSelectionSettings, que permite definir filtros nos anúncios complementares por tipo de criativo, porcentagem de ajuste aproximado, tipo de recurso e critérios de tamanho. Para mais informações sobre essas configurações, consulte a documentação da API CompanionAdSelectionSettings da IMA.

Os objetos CompanionAd retornados por getCompanionAds agora podem ser usados para mostrar os anúncios complementares na página usando estas diretrizes:

1. Crie um espaço para anúncio complementar <div> do tamanho necessário na página.
2. No manipulador de eventos do STARTED evento, recupere o Ad objeto chamando getAd().
3. Use getCompanionAds() para receber uma lista de anúncios complementares que correspondem ao tamanho do espaço do anúncio complementar e a CompanionAdSelectionSettings e têm o mesmo número de sequência do criativo principal. Os criativos sem um atributo de sequência são tratados como tendo o número de sequência 0.
4. Receba o conteúdo de uma instância CompanionAd e defina como o HTML interno do <div> do slot de anúncio.

Código de amostra

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

Mostrar anúncios complementares flexíveis de display

O SDK do IMA agora é compatível com anúncios complementares flexíveis. Esses anúncios complementares podem ser redimensionados para corresponder ao tamanho do espaço do anúncio. Eles preenchem 100% da largura da div pai e redimensionam a altura para se ajustar ao conteúdo do acompanhante. Eles são definidos usando o tamanho complementar Fluid no Ad Manager. Confira na imagem a seguir onde definir esse valor.

Complementares fluidos da GPT

Ao usar os complementos da GPT, é possível declarar um slot de complemento flexível atualizando o segundo parâmetro do método 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>

Acompanhantes flexíveis da API Ad

Ao usar a API Ad para anúncios complementares, você pode declarar um slot complementar flexível atualizando google.ima.CompanionAdSelectionSettings.SizeCriteria para o valor 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>