Adicionar suporte a anúncios complementares

Selecione a plataforma: HTML5 Android iOS

Talvez você queira associar seus espaços de anúncio HTML in-page a espaços de anúncio em vídeo ou anúncios overlay. Essa relação entre locais de anúncios associados é chamada de principal-complementar.

Além de solicitar anúncios principais em vídeo e sobrepostos, você pode usar o SDK do IMA para mostrar 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. Reserve seus 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, quando um único comprador controla todos os anúncios na página, também é conhecida como roadblock.

2. Solicite seus anúncios complementares

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

3. Mostre 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 mostrados automaticamente, desde que haja locais de anúncios complementares declarados na página HTML e 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 são:

  • 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 ausente.
  • Locais de espaços de anúncios complementares pré-carregados para players de vídeo clique para assistir.
  • Renderização complementar automatizada, incluindo HTMLResource e iFrameResource.

• Manualmente pela 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 HTML complementares no seu site. Recomendamos que a maioria dos publishers use a GPT. O SDK HTML5 reconhece os locais da GPT se ela estiver carregada na página da Web principal (não em um iframe). Você pode encontrar informações mais detalhadas sobre como usar a 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 HTML5 em um iframe

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

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

Para que seus complementares sejam mostrados 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 pode haver nenhuma 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 locais de anúncios complementares em HTML

Esta seção explica como declarar anúncios complementares em HTML usando a GPT e fornece um exemplo de código para diferentes cenários. Para o SDK HTML5, é necessário adicionar um pouco de JavaScript à página HTML e declarar os locais de anúncios complementares.

Observação: em cada um dos exemplos a seguir, forneça um network e unit-path válidos na chamada do 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ços de anúncios
• Exemplo 2: implementação de espaço de anúncio dinâmico
• Exemplo 3: locais de anúncio carregados previamente

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

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

Confira um exemplo da 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 uma implementação funcional.

Exemplo 2: implementação de espaço de anúncio dinâmico

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

Observação: quando o player de vídeo está prestes a mostrar os anúncios, ele pede os locais. Verifique se os locais 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 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 clicar em um vídeo clique para assistir. Nesse caso, você precisa da capacidade de solicitar um anúncio normal para preencher o espaço do anúncio antes que o anúncio complementar seja solicitado. Para oferecer suporte a esse caso de uso, você pode mostrar anúncios da Web padrão no local complementar. Verifique se os anúncios da Web estão segmentados para os locais complementares. Você pode segmentar os locais complementares da mesma forma que segmentaria os locais de anúncios da Web padrão.

Observação: o exemplo de código a seguir é exatamente o mesmo 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 de anúncios do seu anúncio de pré-carregamento , em vez do seu 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 uma implementação funcional.

Usar anúncios complementares com a API Ad

Esta seção descreve como mostrar anúncios complementares usando a API Ad.

Mostrar anúncios complementares

Para mostrar anúncios complementares, primeiro acesse uma referência a um objeto Ad por meio de qualquer um dos AdEvent eventos 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 CompanionAd objetos. Aqui, você tem a opção de especificar CompanionAdSelectionSettings, que permite definir filtros nos anúncios complementares para tipo de criativo, porcentagem de ajuste próximo, tipo de recurso e critérios de tamanho. Para mais informações sobre essas configurações, consulte a documentação da API CompanionAdSelectionSettingsdo 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 do anúncio complementar <div> do tamanho necessário na página.
2. No manipulador de eventos para o STARTED evento, recupere o Ad objeto 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 com um atributo de sequência ausente são tratados como tendo o número de sequência 0.
4. Receba o conteúdo de uma CompanionAd instância e defina-o como o HTML interno da <div> do local 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>

Mostrar anúncios complementares flexíveis

O IMA agora oferece suporte a 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 principal e, em seguida, redimensionam a altura para ajustar o conteúdo do complementar. Eles são definidos usando o tamanho complementar Fluid no Ad Manager. Confira a imagem a seguir para saber onde definir esse valor.

Complementares flexíveis da GPT

Ao usar complementares da GPT, você pode declarar um local 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>

Complementares flexíveis da API Ad

Ao usar a API Ad para anúncios complementares, você pode declarar um local 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>