Como evitar erros comuns de implementação
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
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. 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 sugestão de abordagem para corrigir o problema mostrado.
Essa lista não representa uma lista completa de 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 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 de 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>
|
Formas sugeridas de 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: depender de listeners de tag de script gpt.js
Descrição do caso de uso de alto nível |
A suposição de que a API GPT está pronta para ser chamada quando o arquivo JavaScript
gpt.js é carregado está errada, 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: depender da sintaxe de código ofuscado
Descrição do caso de uso de alto nível |
Se você depender da sintaxe precisa do código da biblioteca GPT minimizada, provavelmente vai encontrar 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 o 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 |
Só é possível confiar na API pública. 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 de 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. As mudanças de tempo nos componentes internos da GPT podem mostrar esse
tipo de comportamento incorreto por quebras.
|
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 errada de chamadas para a GPT
Descrição de caso de uso de alto nível |
Disputas podem criar falhas à medida que os componentes internos da GPT evoluem. Um conjunto de instruções ordenado incorretamente 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 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
- Definir configurações no nível da página
- Definir slots
- enableServices()
- Slots de exibição
-
Enable-Define-Display
- Definir configurações no nível da página
- enableServices()
- Definir slots
- Slots de exibição
|
Cenário 7: fazer uso indevido de fechamentos e do 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, se uma variável for reatribuída, o novo valor dela será usado quando a função
de fechamento que a capturou for executada mais tarde. 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
sobre as regras de escopo do JavaScript.
|
Cenário 8: mover contêineres de slot no DOM depois de chamar o display
Descrição de 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"));
|
Formas sugeridas de 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");
|
Cenário 9: substituir APIs do navegador
Descrição de caso de uso de alto nível |
A substituição de APIs do navegador (também conhecida como monkey patching e polyfilling) não é aceita na GPT.
Essa prática pode interromper scripts de terceiros, como o GPT, de maneiras inesperadas.
|
Exemplo de snippet de código com erro |
// Incorrect: Overwriting window.fetch
const { fetch: originalFetch } = window;
window.fetch = (...args) => {
console.log('Fetching!');
return originalFetch(resource, config);
};
|
Sugestões para corrigir o erro |
// Correct: Avoid making changes to browser APIs.
// If you need custom logic, consider leaving the browser API intact.
const myFetch = (...args) => {
console.log('Fetching!');
return window.fetch(...args);
}
|
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-07-25 UTC.
[null,null,["Última atualização 2025-07-25 UTC."],[[["\u003cp\u003eAvoid unofficial copies of GPT JavaScript libraries, always access them from an official Google domain.\u003c/p\u003e\n"],["\u003cp\u003eUtilize \u003ccode\u003egoogletag.cmd.push\u003c/code\u003e to queue functions and ensure they execute when GPT is ready, rather than relying on script tag listeners or checking the \u003ccode\u003egoogletag\u003c/code\u003e object directly.\u003c/p\u003e\n"],["\u003cp\u003eStrictly adhere to the documented GPT API and refrain from relying on obfuscated code or overwriting any GPT functions or variables to prevent breakages.\u003c/p\u003e\n"],["\u003cp\u003eMaintain the correct order of GPT calls, like defining page-level settings and slots before enabling services and displaying ads, to avoid race conditions.\u003c/p\u003e\n"],["\u003cp\u003eBe mindful of JavaScript variable scoping and closures, especially when using \u003ccode\u003egoogletag.cmd.push\u003c/code\u003e, to prevent unexpected behavior due to delayed execution.\u003c/p\u003e\n"],["\u003cp\u003eEnsure slot containers are positioned correctly in the DOM before calling \u003ccode\u003edisplay\u003c/code\u003e to avoid reflows and unpredictable rendering.\u003c/p\u003e\n"],["\u003cp\u003eRefrain from overwriting browser APIs, as it can negatively impact the functionality of third-party scripts like GPT.\u003c/p\u003e\n"]]],["The content outlines unsupported methods of implementing GPT (Google Publisher Tag) that may cause unpredictable ad serving issues. Key actions to avoid include: using unofficial GPT JavaScript libraries, relying on script tag listeners or the `googletag` object to determine API readiness, using obfuscated code syntax, overwriting GPT functions/variables, mis-ordering GPT calls, and misusing JavaScript variable scoping. Correct implementations involve using Google-hosted libraries, leveraging `googletag.cmd.push`, respecting API timing, and modifying the DOM before calling display. Also, avoid overwriting browser APIs.\n"],null,[]]