Adicionar suporte a anúncios complementares

Selecione a plataforma: HTML5 Android iOS

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

Além de solicitar anúncios principais de vídeo e sobreposição, é possível 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 seus anúncios complementares

Primeiro, é preciso reservar os anúncios complementares que você quer exibir com os anúncios principais. É possível programar anúncios complementares 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 roadblock.

2. Solicitar anúncios complementares

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

3. Mostrar anúncios complementares

Há duas maneiras de renderizar anúncios complementares:

• Automaticamente, usando a Tag de Publisher do Google (GPT).

  Se você estiver usando a GPT para implementar seus anúncios complementares, eles serão exibidos automaticamente, desde que haja espaços do 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 ser igual). Estas são algumas das vantagens de usar a GPT:

  • Conhecimento do espaço dos anúncios complementares.
  • Preenchimento complementar da rede do editor, se a resposta VAST contiver menos anúncios complementares do que o número de espaços definidos na página HTML.
  • Preenchimento automático complementar se um anúncio em vídeo estiver ausente.
  • Espaços do anúncio complementar pré-carregados para players de vídeo clique para assistir.
  • Renderização de companion automatizada, incluindo HTMLResource e iFrameResource.

• Manualmente usando a API Ad.

Usar anúncios complementares com a Tag de Publisher do Google

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

Observação: quando você usa o SDK do 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 divulgar isso aos visitantes para obedecer ao requisito de divulgação de coleta e uso de dados do seu contrato com o Google.

Se você hospedar o SDK do HTML5 em um iframe

Se você atender aos dois critérios a seguir, será necessário incluir um script de proxy extra para que os complementares 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 complementares sejam exibidos nesse cenário, carregue o script de proxy da 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 deve haver GPT carregada no 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 de anúncios complementares em HTML

Nesta seção, explicamos como declarar anúncios complementares em HTML usando a GPT e fornecemos exemplos de código para diferentes cenários. Para o SDK de HTML5, é necessário adicionar um pouco de JavaScript à página HTML e declarar os espaços do anúncio complementares.

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

• Exemplo 1: implementação básica de espaço do anúncio
• Exemplo 2: implementação de espaço do anúncio dinâmico
• Exemplo 3: espaços do anúncio 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 espaço do anúncio. O espaço do anúncio declarado é de 728 x 90 px. A GPT tenta preencher o espaço com os anúncios complementares retornados na resposta VAST que correspondem a esse tamanho. Depois que os espaços do anúncio forem declarados, a função googletag.display() poderá renderizá-los onde quer que seja chamada na página. 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 codepen a seguir para ver uma implementação em funcionamento.

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

Às vezes, você não sabe quantos espaços do 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 espaços do anúncio enquanto a página é renderizada. Este exemplo é idêntico ao Exemplo 1, exceto que ele registra os espaços do anúncio onde eles são realmente mostrados.

Observação: quando o player de vídeo está prestes a exibir os anúncios, ele solicita os espaços. Verifique se os espaços 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 espaço do 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 após o carregamento da página. Por exemplo, um anúncio complementar pode ser carregado somente depois que o usuário clica em um vídeo de clique para assistir. Nesse caso, você precisa solicitar um anúncio comum para preencher o espaço do anúncio antes que o anúncio complementar seja solicitado. Para oferecer suporte a esse caso de uso, é possível exibir anúncios padrão da Web 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 você segmentaria espaços de anúncio padrão da Web.

Observação : o exemplo de código a seguir é exatamente igual ao fornecido para o Exemplo 1, com exceção da seção em negrito. Nesse caso, você fornece a rede de publicidade e o caminho 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 CodePen a seguir para ver uma implementação em funcionamento.

Usar anúncios complementares com a API Ad

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

Mostrar anúncios complementares

Para mostrar anúncios complementares, primeiro receba uma referência a um objeto Ad por qualquer um dos eventos AdEvent enviados do AdsManager. Recomendamos usar o evento AdEvent.STARTED, já que a exibição de anúncios complementares precisa 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ê tem a opção de especificar CompanionAdSelectionSettings, que permite definir filtros nos anúncios complementares para 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 IMA CompanionAdSelectionSettings.

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

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

Exemplo de código

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

Exibir anúncios complementares flexíveis

O 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 complementar. Eles são definidos usando o tamanho complementar Fluid no Ad Manager. Veja na imagem a seguir onde definir esse valor.

Complementares fluidos da GPT

Ao usar complementares da GPT, é possível declarar um espaço complementar 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>

Anúncios complementares flexíveis da API Ad

Ao usar a API Ad para anúncios complementares, é possível declarar um espaço 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>