Os cenários a seguir representam alguns dos erros mais comuns observados na implementação da GPT. Embora essas implementações pareçam funcionar bem com a versão atual da GPT, não é garantido que elas continuarão a fazer isso no futuro. Nos casos mais 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 abordagem sugerida para corrigir o problema mostrado.
Esta não é uma lista completa dos possíveis problemas, mas serve como um guia útil para identificar os tipos de problemas que podem precisar ser resolvidos.
Além disso, dependendo da implementação, talvez seja necessário procurar todos os locais em que essas mudanças serão necessárias no seu site.
Erros comuns
Cenário 1: uso de cópias não oficiais das bibliotecas JavaScript da GPT
| Descrição de alto nível do caso de uso | Hospedar gpt.js, pubads_impl.js ou qualquer biblioteca que eles carreguem dos seus próprios servidores ou carregar 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 de correção do erro |
// Correct: Access these files from a Google domain <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script> // Also correct, if using Limited Ads <script async src="https://pagead2.googlesyndication.com/tag/js/gpt.js"></script> |
Cenário 2: depende de listeners de tags de script gpt.js
| Descrição de alto nível do caso de uso |
Supor que a API GPT está pronta para ser chamada quando o arquivo JavaScript gpt.js for carregado está errado, já que algumas partes da API são fornecidas pelo arquivo pubads_impl.js. Portanto, é incorreto confiar na API (incluindo frameworks) nos listeners de eventos anexados à tag de script.
|
| 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 de correção do 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 |
O googletag.cmd mantém uma lista de comandos que serão executados assim que a GPT
estiver pronta. Essa é a maneira correta de garantir que seu callback seja executado quando a GPT for carregada.
|
Cenário 3: verificando o objeto googletag para saber se a GPT está pronta
| Descrição de alto nível do caso de uso |
Como a API GPT pode não estar pronta quando o arquivo JavaScript gpt.js for carregado
ou quando o objeto googletag estiver definido, a verificação desse objeto para saber se
a API GPT está disponível não é 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 de correção do 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 estiver pronta para ser chamada. Assim, você poderá fazer declarações confiáveis. |
Cenário 4: depender de sintaxe de código ofuscada
| Descrição de alto nível do caso de uso |
Se você usar a sintaxe precisa do código da biblioteca GPT reduzida, provavelmente
enfrentará falhas. Limite o uso à API documentada no Guia de referência da API, já que estamos sempre mudando o 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 de correção do 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 | Apenas a API pública pode ser usada. Caso seja possível detectar se o PubAdsService está totalmente carregado, temos um valor booleano googletag.pubadsReady. |
Cenário 5: substituição de qualquer função ou variável da GPT
| Descrição de alto nível do caso de uso | Casos de uso baseados na substituição de qualquer função ou variável usada pela GPT podem ser corrompidos a qualquer momento, já que esse não é um caso de uso compatível. Mudanças de tempo nos componentes internos da GPT podem gerar esse tipo de comportamento incorreto por falhas. |
| Exemplo de snippet de código com erro |
// Incorrect: Haphazardly overwriting a googletag.* property. googletag.cmd = []; |
| Sugestões de correção do 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 de chamadas para a GPT
| Descrição de alto nível do caso de uso | Disputas podem criar rupturas à medida que os componentes internos da GPT evoluem. Um conjunto incorreto de instruções que eram funcionais devido a tempos específicos na execução pode não permanecer operacional 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 de correção do 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 |
Para evitar disputas, respeite o tempo normal da GPT. Veja alguns exemplos
de ordens parciais válidas:
|
Cenário 7: uso indevido de interdições e escopo de variáveis JavaScript
| Descrição de alto nível do caso de uso |
Suposições incorretas sobre o escopo de variáveis JavaScript e o valor das variáveis
capturadas 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 de correção do 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, as interdições capturam variáveis por referência e não por valor. Isso significa que, se uma variável for reatribuída, o novo valor será usado quando a função que a capturou for executada posteriormente. Assim, o comportamento do código na interdição pode mudar dependendo se o callback é executado imediatamente ou atrasado. No caso de carregamento da GPT assíncrona, dependendo da velocidade com que a GPT carrega os callbacks na fila de comando, eles poderão ser executados imediatamente ou não. No exemplo acima, isso altera o comportamento dos comandos na fila. Para evitar quaisquer problemas, é preciso escrever o código sem presumir que as funções colocadas na fila de comandos serão executadas imediatamente e tenha cuidado com as regras de escopo do JavaScript. |
Cenário 8: mover contêineres de slot no DOM após chamar display
| Descrição de alto nível do caso de uso | Mover ou inserir contêineres de slot no DOM depois de chamar a exibição pode levar a um reflow indesejado e um 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 de correção do 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");
|