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
<scriptasyncsrc="https://www.example.com/tag/js/gpt.js"></script>
Formas sugeridas de corrigir o erro
// Correct: Access these files from a Google domain
<scriptsrc="https://securepubads.g.doubleclick.net/tag/js/gpt.js"crossorigin="anonymous"async></script>
// Also correct, if using Limited Ads
<scriptsrc="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.
// 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(typeofgoogletag!='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.
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 displaygoogletag.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 displaydocument.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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Ú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,[]]