Evitare errori comuni di implementazione
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
I seguenti scenari rappresentano alcuni degli errori più comuni osservati durante l'implementazione di GPT. Sebbene queste implementazioni possano funzionare correttamente con la versione corrente di GPT, non è garantito che continueranno a farlo anche in futuro. Nella
nella maggior parte dei casi estremi, queste implementazioni possono causare interruzioni imprevedibili della pubblicazione di annunci.
Sono considerate implementazioni non supportate.
Ogni scenario include un approccio suggerito per risolvere il problema mostrato.
Tieni presente che questo elenco non rappresenta un elenco esaustivo dei potenziali problemi, ma dovrebbe servire da guida utile per identificare i tipi di problemi che potrebbero dover essere affrontati.
Inoltre, a seconda della tua implementazione, potrebbe essere necessario cercare tutti i punti in cui
tali modifiche potrebbero essere necessarie all'interno del tuo sito.
Errori comuni
Scenario 1: utilizzo di copie non ufficiali delle librerie JavaScript GPT
Descrizione del caso d'uso di alto livello |
Hosting di gpt.js, pubads_impl.js o qualsiasi libreria caricata dai tuoi server oppure
caricando questi file da una fonte non ufficiale.
|
Esempio di snippet di codice con errore |
// Incorrect: Accessing these files from an unofficial source
<script async src="https://www.example.com/tag/js/gpt.js"></script>
|
Metodi suggeriti per correggere l'errore |
// 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>
|
Scenario 2: utilizzo dei listener di tag di script gpt.js
Descrizione del caso d'uso generale |
È sbagliato assumere che l'API GPT sia pronta per essere chiamata quando viene caricato il file JavaScript
gpt.js , poiché alcune parti dell'API sono fornite dal
pubads_impl.js file. Affidarsi in qualsiasi modo (inclusi i framework) all'API
dai listener di eventi associati al tag script non sono quindi corretti.
|
Esempio di snippet di codice con errore |
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);
|
Metodi suggeriti per correggere l'errore |
// 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);
|
Spiegazione / descrizione della correzione |
googletag.cmd gestisce un elenco di comandi che verranno eseguiti non appena il GPT sarà pronto. Questo è il modo corretto per assicurarti che il callback venga eseguito dopo il caricamento di GPT.
|
Scenario 3: controllo dell'oggetto googletag per sapere se GPT è pronto
Descrizione del caso d'uso di alto livello |
Poiché l'API GPT potrebbe non essere pronta quando viene caricato il file JavaScript gpt.js o quando viene definito l'oggetto googletag , controllare questo oggetto per verificare se l'API GPT è disponibile non è affidabile.
|
Esempio di snippet di codice con errore |
// Incorrect: Relying on the presence of the googletag object
// as a check for the GPT API.
if (typeof googletag != 'undefined') {
functionProcessingGPT();
}
|
Metodi suggeriti per correggere l'errore |
// Correct: Relying on googletag.apiReady as a check for the GPT API.
if (window.googletag && googletag.apiReady) {
functionProcessingGPT();
}
|
Spiegazione/descrizione della correzione |
GPT completerà il flag booleano
googletag.apiReady non appena
l'API è pronta per essere chiamata,
così puoi fare asserzioni affidabili.
|
Scenario 4: utilizzo della sintassi del codice offuscato
Descrizione del caso d'uso di alto livello |
Se ti affidi alla sintassi esatta del codice della libreria GPT minimizzata, quasi
che subiranno sicuramente rotture. Limita il tuo utilizzo all'API documentata nella Guida di riferimento API, poiché apportiamo modifiche continue
il funzionamento interno di GPT per migliorare continuamente.
Ad esempio, un requisito comune è rilevare quando PubAdsService è completamente caricato per chiamare refresh() .
|
Esempio di snippet di codice con errore |
// Incorrect: Relying on an obfuscated property.
if (googletag.pubads().a != null) {
functionProcessingGPT();
}
|
Metodi suggeriti per correggere l'errore |
// Correct: Relying on public GPT API methods
// (i.e. googletag.pubadsReady in this case).
if(window.googletag && googletag.pubadsReady) {
functionProcessingGPT();
}
|
Spiegazione/descrizione della correzione |
È possibile fare affidamento solo sull'API pubblica. In caso di rilevamento di se PubAdsService è
completamente caricato, abbiamo un valore booleano
googletag.pubadsReady.
|
Scenario 5: sovrascrittura di qualsiasi funzione o variabile di GPT
Descrizione del caso d'uso di alto livello |
I casi d'uso basati sulla sovrascrittura di qualsiasi funzione o variabile utilizzata da GPT potrebbero non funzionare in qualsiasi momento
in quanto non è un caso d'uso supportato. Le modifiche alle tempistiche nei componenti interni di GPT possono rivelare questo
comportamento errato per malfunzionamenti.
|
Esempio di snippet di codice con errore |
// Incorrect: Haphazardly overwriting a googletag.* property.
googletag.cmd = [];
|
Metodi suggeriti per correggere l'errore |
// Correct: Never overwrite googletag.* properties if they already exist.
// Always check before assigning to them.
googletag.cmd = googletag.cmd || [];
|
Scenario 6: ordine errato delle chiamate al GPT
Descrizione del caso d'uso di alto livello |
Le condizioni di gara possono creare interruzioni con l'evoluzione degli elementi interni di GPT. Un errore
un insieme ordinato di istruzioni operative a causa di tempistiche specifiche di esecuzione
potrebbero non rimanere operativi in futuro.
|
Esempio di snippet di codice con errore |
// Incorrect: Setting page-level key-value targeting after calling
// googletag.enableServices().
googletag.enableServices();
googletag.defineSlot(...);
googletag.pubads().setTargeting(e, a);
|
Metodi suggeriti per correggere l'errore |
// Correct: Setting page-level key-value targeting before calling
// googletag.enableServices().
googletag.pubads().setTargeting(e, a);
googletag.defineSlot(...);
googletag.enableServices();
|
Spiegazione/descrizione della correzione |
Evita le gare d'effetto rispettando le tempistiche normali di GPT. Ecco alcuni esempi di ordini parziali validi:
-
Definisci-Attiva-Display
- Definire le impostazioni a livello di pagina
- Definire gli slot
- enableServices()
- Slot di visualizzazione
-
Attiva-Definisci-Display
- Definisci le impostazioni a livello di pagina
- enableServices()
- Definisci gli slot
- Slot di visualizzazione
|
Scenario 7: uso improprio delle chiusure e dell'ambito delle variabili JavaScript
Descrizione del caso d'uso di alto livello |
Presupposti errati sull'ambito delle variabili JavaScript e sul valore delle variabili acquisite nella funzione passata a googletag.cmd.push .
|
Esempio di snippet di codice con errore |
// 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]);
})
}
}
|
Metodi suggeriti per correggere l'errore |
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]);
}
}
)
|
Spiegazione / descrizione della correzione |
In JavaScript, le chiusure acquisiscono le variabili per riferimento anziché per valore. Ciò significa
che se una variabile viene riassegnata, il suo nuovo valore verrà utilizzato quando la funzione
che lo ha acquisito in un secondo momento. Pertanto, il comportamento del codice nella chiusura
può cambiare a seconda che il callback venga eseguito immediatamente o in ritardo.
Nel caso di GPT caricato in modo asincrono, a seconda della velocità di caricamento del tag GPT
i callback sulla coda dei comandi potrebbero essere eseguiti immediatamente o meno. Nella precedente
Ad esempio, questo modifica il comportamento dei comandi in coda.
Per evitare problemi, il codice deve essere scritto senza presupporre che le funzioni messe nella coda di comandi vengano eseguite immediatamente e occorre prestare attenzione alle regole di ambito di JavaScript.
|
Scenario 8: spostamento dei container di slot all'interno del DOM dopo la chiamata del display
Descrizione del caso d'uso generale |
Lo spostamento o l'inserimento di contenitori degli slot nel DOM dopo aver chiamato il metodo display può portare a un reflow indesiderato e a un comportamento imprevedibile in GPT.
|
Esempio di snippet di codice con errore |
// 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"));
|
Metodi suggeriti per correggere l'errore |
// 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");
|
Scenario 9: sovrascrittura delle API del browser
Descrizione del caso d'uso generale |
La sovrascrittura (ovvero applicazione di patch a scimmia, polyfill) delle API del browser non è supportata in GPT.
Questa pratica potrebbe causare l'interruzione di script di terze parti come GPT in modi imprevisti.
|
Esempio di snippet di codice con errore |
// Incorrect: Overwriting window.fetch
const { fetch: originalFetch } = window;
window.fetch = (...args) => {
console.log('Fetching!');
return originalFetch(resource, config);
};
|
Metodi suggeriti per correggere l'errore |
// 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);
}
|
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-07-25 UTC.
[null,null,["Ultimo aggiornamento 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,[]]