Como evitar erros comuns de implementação

Os cenários a seguir representam alguns dos erros mais comuns observados quando a implementação da GPT. Embora essas implementações pareçam funcionar bem com o modelo versão da GPT, não podemos garantir que continuarão a fazer isso no futuro. Na Na maioria dos casos extremos, essas implementações podem causar falhas imprevisíveis na veiculação de anúncios. Elas são consideradas implementações sem suporte.

Cada cenário inclui uma sugestão de abordagem para corrigir o problema mostrado.

Esta não é uma lista completa dos possíveis problemas, mas deve servir como um guia útil para identificar os tipos de problemas que podem a serem resolvidos.

Além disso, dependendo da implementação, talvez seja necessário procurar todos os locais em que essas mudanças podem ser necessárias no seu site.

Erros comuns

Cenário 1: uso de cópias não oficiais das bibliotecas JavaScript da GPT

Descrição do caso de uso de alto nível Hospedar gpt.js, pubads_impl.js ou as bibliotecas carregadas de seus próprios servidores, ou carregando esses arquivos de uma fonte não oficial.
Exemplo de snippet de código com erro
// Incorrect: Accessing these files from an unofficial source
<script async src="https://www.example.com/tag/js/gpt.js"></script>
Sugestões para corrigir o erro
// Correct: Access these files from a Google domain
<script src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" crossorigin="anonymous" async></script>
// Also correct, if using Limited Ads
<script src="https://pagead2.googlesyndication.com/tag/js/gpt.js" async></script>

Cenário 2: usar listeners de tag de script gpt.js

Descrição do caso de uso de alto nível Supondo que a API GPT está pronta para ser chamada quando o arquivo JavaScript O carregamento de gpt.js está errado, já que algumas partes da API são fornecidas pelo arquivo pubads_impl.js. confiar de qualquer forma na API (incluindo frameworks) nos listeners de eventos anexados à tag script está incorreto.
Exemplo de snippet de código com erro
var tag = document.createElement('script');
tag.type = 'text/javascript';
tag.src = (useSSL ? 'https:' : 'http:') +
        '//www.googletagservices.com/tag/js/gpt.js';
// Incorrect: Attaching a callback to the script's onload event.
tag.onload = callback;
var node = document.getElementsByTagName('script')[0];
node.parentNode.insertBefore(tag, node);
Sugestões para corrigir o erro
// Make sure that googletag.cmd exists.
window.googletag = window.googletag || {};
googletag.cmd = googletag.cmd || [];
// Correct: Queueing the callback on the command queue.
googletag.cmd.push(callback);
Explicação / descrição da correção googletag.cmd mantém uma lista de comandos que serão executados assim que a GPT estiver pronto. Essa é a maneira correta de garantir que o callback seja executado quando a GPT for carregada.

Cenário 3: verificar o objeto googletag para saber se a GPT está pronta

Descrição do caso de uso de alto nível Como a API da GPT pode não estar pronta quando o arquivo JavaScript gpt.js for carregado ou quando o objeto googletag for definido, ele vai ser verificado se a API da GPT disponível não for confiável.
Exemplo de snippet de código com erro
// Incorrect: Relying on the presence of the googletag object
// as a check for the GPT API.
if (typeof googletag != 'undefined') {
 functionProcessingGPT();
}
Sugestões para corrigir o erro
// Correct: Relying on googletag.apiReady as a check for the GPT API.
if (window.googletag && googletag.apiReady) {
 functionProcessingGPT();
}
Explicação / descrição da correção A GPT preencherá a sinalização booleana googletag.apiReady assim que a API está pronta para ser chamada, para que você possa fazer declarações confiáveis.

Cenário 4: confiar na sintaxe de código ofuscada

Descrição do caso de uso de alto nível Se você depende de uma sintaxe precisa do código da biblioteca GPT reduzida, certamente sofrem falhas. Use a API documentada no Guia de referência da API, já que estamos sempre mudando ao funcionamento interno da GPT para melhorias constantes.
Por exemplo, um requisito comum é detectar quando PubAdsService está totalmente carregado para chamar refresh().
Exemplo de snippet de código com erro
// Incorrect: Relying on an obfuscated property.
if (googletag.pubads().a != null) {
 functionProcessingGPT();
}
Sugestões para corrigir o erro
// Correct: Relying on public GPT API methods
// (i.e. googletag.pubadsReady in this case).
if(window.googletag && googletag.pubadsReady) {
 functionProcessingGPT();
}
Explicação / descrição da correção Somente a API pública é confiável. Para detectar se PubAdsService está totalmente carregado, temos um valor booleano googletag.pubadsReady.

Cenário 5: substituir qualquer função ou variável da GPT

Descrição do caso de uso de alto nível Os casos de uso baseados na substituição de qualquer função ou variável usada pela GPT podem ser corrompidos a qualquer momento. porque esse não é um caso de uso aceito. Mudanças na programação dos componentes internos da GPT podem causar isso comportamento incorreto devido a falhas.
Exemplo de snippet de código com erro
// Incorrect: Haphazardly overwriting a googletag.* property.
googletag.cmd = [];
Sugestões para corrigir o erro
// Correct: Never overwrite googletag.* properties if they already exist.
// Always check before assigning to them.
googletag.cmd = googletag.cmd || [];

Cenário 6: ordem incorreta das chamadas para a GPT

Descrição do caso de uso de alto nível Disputas podem criar falhas à medida que os componentes internos da GPT evoluem. Um erro de conjunto ordenado de instruções que eram funcionais devido a tempos específicos na execução podem não continuar funcionando no futuro.
Exemplo de snippet de código com erro
// Incorrect: Setting page-level key-value targeting after calling
// googletag.enableServices().
googletag.enableServices();
googletag.defineSlot(...);
googletag.pubads().setTargeting(e, a);
Sugestões para corrigir o erro
// Correct: Setting page-level key-value targeting before calling
// googletag.enableServices().
googletag.pubads().setTargeting(e, a);
googletag.defineSlot(...);
googletag.enableServices();
Explicação / descrição da correção Evite disputas respeitando o tempo normal da GPT. Exemplo válido as ordenações parciais incluem:
  • Definir-Ativar-Exibir
    1. Definir configurações no nível da página
    2. Definir slots
    3. enableServices()
    4. Slots de exibição
  • Ativar-Definir-Exibir
    1. Definir configurações no nível da página
    2. enableServices()
    3. Definir slots
    4. Slots de exibição

Cenário 7: uso indevido de interdições e escopo de variáveis JavaScript

Descrição do caso de uso de alto nível Suposições incorretas sobre o escopo das variáveis JavaScript e o valor delas capturada na função transmitida para googletag.cmd.push.
Exemplo de snippet de código com erro
// Incorrect: Variable x is declared outside the anonymous function
// but referenced within it.
for (var x = 0; x < slotCount; x++) {
 window.googletag.cmd.push(
  function(){
    // If GPT is not yet loaded, this code will be executed subsequently when
    // the command queue is processed. Every queued function will use the last value
    // assigned to x (most likely slotCount).
    // This is because the function closure captures the reference to x,
    // not the current value of x.
    window.googletag.display(slot[x]);
  })
 }
}
Sugestões para corrigir o erro
window.googletag.cmd.push(
 function(){
  // Correct: We both declare and reference x inside the context of the function.
  for (var x = 0; x < slotCount; x++){
   window.googletag.display(slot[x]);
  }
 }
)
Explicação / descrição da correção

Em JavaScript, os fechamentos capturam variáveis por referência e não por valor. Isso significa que que, se uma variável for reatribuída, seu novo valor será usado quando a função que o capturou será executado posteriormente. Assim, o comportamento do código na interdição pode mudar dependendo se o callback é executado imediatamente ou atrasado.

No caso de GPT carregada de maneira assíncrona, dependendo da rapidez com que a GPT carrega o callbacks na fila de comandos podem ser executados imediatamente ou não. Na última exemplo, isso altera o comportamento dos comandos na fila.

Para evitar problemas, o código precisa ser escrito sem a suposição de que as funções colocados na fila de comandos serão executados imediatamente, e é necessário tomar cuidado em relação às regras de escopo do JavaScript.

Cenário 8: mover contêineres de slot no DOM depois de chamar o display

Descrição do caso de uso de alto nível Mover ou inserir contêineres de slot no DOM após chamar a tela pode gerar reflow indesejado e comportamento imprevisível na GPT.
Exemplo de snippet de código com erro
// Incorrect: Moving slot containers after calling display
googletag.defineSlot("/1234/travel/asia", [728, 90], "div-gpt-ad-123456789-0");
googletag.enableServices();
googletag.display("div-gpt-ad-123456789-0");
...
// Inserting another element before the slot container, pushing the slot container down the page.
document.body.insertBefore(someOtherElement, document.getElementById("div-gpt-ad-123456789-0"));
Sugestões para corrigir o erro
// Correct: Make any DOM order changes before calling display

document.body.insertBefore(someOtherElement, document.getElementById("div-gpt-ad-123456789-0"));
...
googletag.defineSlot("/1234/travel/asia", [728, 90], "div-gpt-ad-123456789-0");
googletag.enableServices();
googletag.display("div-gpt-ad-123456789-0");