Esta página foi traduzida pela API Cloud Translation.

Controlar o carregamento e a atualização de anúncios

Em nossos primeiros passos e exemplos de conceitos básicos, o método display() da biblioteca da Tag do editor do Google (GPT) é usado para registrar e exibir um espaço de anúncio. No entanto, há momentos em que é preferencial ou mesmo necessário separar essas ações para controlar mais precisamente quando o conteúdo do anúncio é carregado. Por exemplo, ao trabalhar com uma plataforma de gerenciamento de consentimento ou solicitar conteúdo do anúncio como resultado de uma ação do usuário.

Neste guia, exploraremos os mecanismos fornecidos pela GPT para controlar o carregamento do conteúdo do anúncio e buscar novos conteúdos sob demanda. O código completo deste exemplo está disponível na página de amostra de solicitações baseadas em eventos.

Controlar o carregamento de anúncios

Por padrão, o comportamento do método display() é registrar, solicitar e renderizar o conteúdo do anúncio em um espaço. A solicitação e a renderização automáticas de conteúdo do anúncio podem ser desativadas pelo método PubAdsService.disableInitialLoad().

Com o carregamento inicial desativado, as chamadas para display() só registram o espaço do anúncio. Nenhum conteúdo do anúncio será carregado até que uma segunda ação seja realizada. Isso permite que você controle com precisão quando as solicitações de anúncios são feitas.

Para evitar solicitações de anúncios não intencionais, disableInitialLoad() precisa ser chamado antes de ativar o serviço e antes de chamar display().

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="Request GPT ads based on events." />
    <title>Event-based ad requests</title>
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(() => {
        // Define the ad slot.
        googletag
          .defineSlot("/6355419/Travel", [728, 90], "div-for-slot")
          .setTargeting("test", "event")
          .addService(googletag.pubads());

        // Disable initial load.
        // This prevents GPT from automatically fetching ads when display is called.
        googletag.pubads().disableInitialLoad();
        googletag.enableServices();
      });
    </script>
    <style></style>
  </head>
  <body>
    <div id="div-for-slot" style="width: 300px; height: 250px"></div>
    <script>
      googletag.cmd.push(() => {
        // Register the ad slot.
        // An ad will not be fetched until refresh is called.
        googletag.display("div-for-slot");

        // Register click event handler.
        document.getElementById("showAdButton").addEventListener("click", () => {
          googletag.cmd.push(() => {
            googletag.pubads().refresh();
          });
        });
      });
    </script>
  </body>
</html>

Neste exemplo, o carregamento inicial é desativado para garantir que nenhuma solicitação de anúncio seja feita e que nenhum conteúdo de anúncio seja renderizado quando display() for chamado. O espaço está pronto para aceitar e exibir um anúncio, mas uma solicitação de anúncio só vai ser feita quando ele for atualizado.

Atualizar

O método PubAdsService.refresh() é usado para preencher slots com novo conteúdo do anúncio. Esse método pode ser usado em slots que ainda tenham para carregar qualquer conteúdo (devido a disableInitialLoad()) ou para substituir o conteúdo de um slot já preenchido. No entanto, somente os slots que foram registrados chamando display() estão qualificados para atualização.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="Request GPT ads based on events." />
    <title>Event-based ad requests</title>
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(() => {
        // Define the ad slot.
        googletag
          .defineSlot("/6355419/Travel", [728, 90], "div-for-slot")
          .setTargeting("test", "event")
          .addService(googletag.pubads());

        // Disable initial load.
        // This prevents GPT from automatically fetching ads when display is called.
        googletag.pubads().disableInitialLoad();
        googletag.enableServices();
      });
    </script>
    <style></style>
  </head>
  <body>
    <div id="div-for-slot" style="width: 300px; height: 250px"></div>
    <button id="showAdButton">Show/Refresh Ad</button>
    <script>
      googletag.cmd.push(() => {
        // Register the ad slot.
        // An ad will not be fetched until refresh is called.
        googletag.display("div-for-slot");

        // Register click event handler.
        document.getElementById("showAdButton").addEventListener("click", () => {
          googletag.cmd.push(() => {
            googletag.pubads().refresh();
          });
        });
      });
    </script>
  </body>
</html>

Neste exemplo modificado, quando um usuário clica no botão "Mostrar/atualizar anúncio", o método refresh() é chamado. Isso aciona uma solicitação para buscar um novo conteúdo do anúncio e carregá-lo no local registrado, substituindo qualquer conteúdo preexistente.

No exemplo acima, o método refresh() é chamado sem parâmetros, o que resulta na atualização de todos os espaços de anúncio registrados. No entanto, também é possível atualizar locais de anúncios específicos transmitindo uma matriz de slots para o método refresh(). Consulte a amostra Atualizar espaços de anúncio para ver um exemplo disso.

Práticas recomendadas

Ao trabalhar com refresh(), é necessário seguir algumas práticas recomendadas.

Não atualize rápido demais.

Atualizar os espaços de anúncio muito rapidamente pode limitar suas solicitações de anúncios. Para evitar isso, evite atualizar slots com mais frequência do que uma vez a cada 30 segundos.
Não chame clear() desnecessariamente

Ao atualizar um espaço de anúncio, não chame PubAdsService.clear() primeiro. Isso é desnecessário, já que refresh() substitui o conteúdo do slot especificado, independentemente de algum conteúdo do anúncio ter sido carregado anteriormente. Chamar clear() imediatamente antes de chamar refresh() só aumentará a quantidade de tempo que um slot em branco será visível para o usuário.

Atualizar apenas os espaços de anúncios visíveis

Usar refresh() para substituir o conteúdo dos espaços do anúncio que nunca são visíveis pode reduzir significativamente a taxa do ActiveView. O ImpressionViewableEvent pode ser usado para determinar quando um espaço do anúncio se torna visível, como no exemplo abaixo.

googletag.cmd.push(function() {
  var REFRESH_KEY = 'refresh';
  var REFRESH_VALUE = 'true';

  googletag.defineSlot('/6355419/Travel',[728, 90], 'div-for-slot')
      .setTargeting(REFRESH_KEY, REFRESH_VALUE)
      .setTargeting('test', 'event')
      .addService(googletag.pubads());

  // Number of seconds to wait after the slot becomes viewable.
  var SECONDS_TO_WAIT_AFTER_VIEWABILITY = 60;

  googletag.pubads().addEventListener('impressionViewable', function(event) {
    var slot = event.slot;
    if (slot.getTargeting(REFRESH_KEY).indexOf(REFRESH_VALUE) > -1) {
      setTimeout(function() {
        googletag.pubads().refresh([slot]);
      }, SECONDS_TO_WAIT_AFTER_VIEWABILITY * 1000);
    }
  });

  googletag.enableServices();
});