Personalizzare un tema WordPress AMP e aggiungere Analytics e AdSense

In un tema WordPress AMP la parte delicata non è “mettere due script in pagina”, ma farlo rispettando i vincoli del formato AMP e senza trasformare il tema in un patchwork ingestibile. Se il tema nasce già con supporto AMP, la strada più pulita è lavorare su child theme, hook e template mirati; se invece il tema è tradizionale, conviene prima capire quale plugin AMP stia generando l’output e dove agganciare Analytics e AdSense senza introdurre markup non valido.

Il punto da tenere fermo è semplice: AMP non perdona HTML libero, JavaScript arbitrario e componenti inseriti a caso. Per questo la personalizzazione va fatta in modo chirurgico, con controlli di validazione dopo ogni modifica. Se salti questa parte, rischi di avere pagine che sembrano corrette nel browser ma non vengono servite come AMP valido, con perdita di traffico, misurazione incompleta o annunci non erogati.

1. Capire dove nasce l’output AMP

Prima di toccare il tema, devi identificare il flusso reale: tema puro, tema + plugin AMP, oppure tema con template dedicati per mobile. In WordPress moderno il caso più frequente è il plugin AMP che converte o sostituisce il template della pagina. In pratica il tema controlla l’aspetto, ma il plugin controlla quali elementi sono ammessi e come vengono trasformati.

Verifica subito quali componenti sono attivi e se il sito espone versioni AMP con percorso dedicato, parametri o endpoint speciali. Una diagnosi rapida evita di modificare il file sbagliato.

wp plugin list --status=active | grep -Ei 'amp|accelerated'
wp theme list --status=active
curl -I https://example.com/articolo/amp/

Se non hai WP-CLI, fai lo stesso controllo dal pannello e dal front-end: cerca nelle impostazioni del plugin AMP il modo in cui genera il markup e annota se usa modalità standard, transitional o reader. È un dettaglio pratico, perché cambia dove conviene intervenire.

2. Personalizzare il tema senza rompere AMP

La regola più utile è questa: le personalizzazioni strutturali vanno nel child theme, quelle legate all’output AMP nei filtri o nei template del plugin, mai in file core del tema. Così puoi aggiornare il tema senza perdere le modifiche e puoi disattivare il child theme o il plugin per tornare indietro rapidamente.

Se devi cambiare colori, spaziature, font o layout di base, lavora su `style.css` del child theme e, se il plugin AMP lo consente, su un file dedicato per AMP. L’errore classico è includere librerie CSS esterne o script custom che AMP non accetta. In AMP il CSS deve restare compatto e, nei limiti del plugin, spesso viene iniettato in un unico blocco con vincoli di dimensione.

Un approccio pratico è tenere separati tre livelli:

• struttura HTML del tema originale;
• stile del child theme compatibile con AMP;
• integrazioni AMP tramite hook del plugin o template specifici.

Se devi intervenire su header, footer o blocchi ricorrenti, controlla se il plugin AMP espone hook per aggiungere contenuti consentiti. Questo è preferibile all’hardcoding nel template, perché ti lascia una via di rollback semplice: disattivi il filtro e il sito torna allo stato precedente.

3. Analytics in AMP: usare il componente giusto, non uno script qualunque

Per Analytics in AMP non devi inserire il classico snippet JavaScript di Google Analytics o di altri strumenti. AMP usa il componente `` con una configurazione JSON specifica. Se provi a forzare il tag standard, il validatore AMP lo considera non conforme.

La logica corretta è: scegli lo strumento di analytics, recupera l’ID o la proprietà, poi integra la configurazione nel punto previsto dal plugin AMP o dal template del tema. In molti casi il plugin offre un campo dedicato per Google Analytics, e quella è la via più sicura. Se il pannello lo consente, preferisci sempre quella strada al codice manuale: meno errori, meno manutenzione, rollback immediato.

Un esempio tipico di configurazione AMP per Analytics, da usare solo come riferimento tecnico, non da incollare ciecamente in ogni installazione, è questo:

<amp-analytics type="googleanalytics">
  <script type="application/json">
  {
    "vars": {
      "account": "UA-XXXXXXX-X"
    },
    "triggers": {
      "trackPageview": {
        "on": "visible",
        "request": "pageview"
      }
    }
  }
  </script>
</amp-analytics>

Nel mondo reale, però, molti siti oggi usano GA4 o un sistema equivalente. In quel caso la configurazione cambia e va allineata al tipo di misura effettivamente attiva. Il punto non è copiare il blocco, ma verificare che il plugin AMP supporti il provider scelto e che il dato passi davvero negli endpoint di raccolta.

Verifica minima dopo l’inserimento:

• la pagina AMP risulta valida;
• non compaiono errori di parsing del JSON;
• la richiesta di tracking parte nei log di rete o nel debugger del browser.

Se il plugin ha un campo impostazione per Analytics, annota il path esatto nel pannello e conserva uno screenshot o un export della configurazione. Quando devi fare rollback, sapere dove è stato inserito l’ID ti evita di cercarlo in tre file diversi.

4. AdSense in AMP: ads consentiti, posizioni e limiti

AdSense in AMP segue la stessa logica: niente script standard di ads, ma componenti AMP dedicati, di solito ``. Anche qui il tema non deve inventarsi markup non supportato. La differenza tra una pagina che monetizza e una che resta vuota spesso è nella precisione del tag e nell’unità pubblicitaria configurata correttamente in AdSense.

La pratica migliore è definire prima la posizione dell’annuncio nel layout: sopra il contenuto, in mezzo all’articolo, in sidebar solo se la versione AMP la prevede, oppure in fondo al post. Poi si inserisce il blocco compatibile con AMP nel template o tramite hook. Se il tema ha più breakpoint o layout differenti, conviene testare una posizione alla volta per non confondere un problema di rendering con un problema di policy o di targeting.

Esempio concettuale di blocco AMP per ads:

<amp-ad width="300" height="250"
  type="adsense"
  data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
  data-ad-slot="1234567890">
</amp-ad>

Non usare questo snippet alla cieca: larghezza, altezza, client e slot devono corrispondere alla tua configurazione reale. Se il formato dell’unità non è compatibile con il contenitore o con il layout scelto, l’annuncio può non apparire o alterare il rendering della pagina.

Per l’inserimento operativo hai tre strade, in ordine di pulizia:

1. campo dedicato nel plugin AMP o nel plugin AdSense compatibile;
2. hook del tema o del child theme per stampare il blocco nel punto giusto;
3. override di template AMP, solo se non hai alternative più semplici.

La prima è quasi sempre la migliore perché riduce il rischio di markup non valido. La terza ha senso solo quando ti serve controllo totale sul layout e sai esattamente quali file vengono caricati nella versione AMP.

5. Controllo del markup: validazione prima di parlare di performance

La validazione AMP non è un optional. Se il markup non è valido, stai misurando e monetizzando una pagina che potrebbe non essere considerata AMP dal client o dal motore di ricerca. Per questo, dopo ogni modifica, controlla il codice sorgente della pagina e il risultato del validatore.

Verifiche pratiche:

curl -s https://example.com/articolo/amp/ | grep -Ei 'amp-analytics|amp-ad|amp-img'

Nel browser, apri gli strumenti di sviluppo e cerca errori legati a componenti AMP mancanti, JSON non valido o attributi non consentiti. Se il sito usa caching aggressivo o CDN, svuota la cache della pagina testata prima di trarre conclusioni: spesso il problema non è nel codice appena cambiato, ma in una versione vecchia ancora servita all’utente.

Un controllo utile è confrontare pagina canonica e pagina AMP:

• stesso contenuto principale;
• stessa coerenza dei metadati essenziali;
• componenti AMP presenti solo nella variante AMP;
• assenza di script non consentiti nella versione AMP.

6. Un flusso di lavoro pulito per tema, Analytics e AdSense

Quando devi mettere insieme personalizzazione del tema, analytics e monetizzazione, conviene lavorare per passi reversibili. Prima prepari il child theme, poi abiliti Analytics, infine aggiungi AdSense. Così, se qualcosa si rompe, sai subito quale modifica ha introdotto il problema.

Una sequenza sensata è questa:

1. crea un child theme e versiona i file modificati;
2. identifica il punto di output AMP con un test su una singola pagina;
3. integra Analytics con il meccanismo nativo del plugin o del tema;
4. aggiungi AdSense in una sola posizione e verifica il rendering;
5. controlla validità AMP, caricamento risorse e presenza delle chiamate di tracking.

Se hai accesso al server, tieni d’occhio i log applicativi e quelli del web server mentre fai i test. In molti casi un errore di PHP nel template AMP non produce una pagina completamente vuota, ma un output parziale con header già inviati. È il classico difetto che passa inosservato finché non confronti la versione AMP con la canonica.

tail -f /var/log/nginx/error.log
journalctl -u php-fpm -f

Se usi Apache invece di Nginx, il principio resta identico: osserva il log di errore del web server e il log PHP-FPM o del processo PHP. Non serve reinventare il debug: serve vedere dove si interrompe la generazione della pagina.

7. Problemi tipici e come evitarli

Il primo problema tipico è l’uso di codice copiato da tutorial generici senza adattarlo al plugin effettivo. In AMP il contesto conta: un blocco valido su un setup può essere ignorato o bloccato su un altro. Il secondo problema è toccare il tema principale invece del child theme, con conseguente perdita delle modifiche al primo aggiornamento. Il terzo è inserire AdSense o Analytics in una posizione che funziona solo visivamente, ma non è compatibile con il parsing AMP.

Un altro errore frequente è non distinguere tra pagina visibile e pagina valida. Una pagina può aprirsi e sembrare corretta, ma avere una violazione che il validatore AMP segnala subito. Per questo conviene sempre controllare il codice sorgente risultante e non fermarsi al rendering del browser.

Se qualcosa non torna, la domanda giusta non è “il sito si vede?”, ma “quale parte del flusso ha smesso di essere compatibile?”. Quasi sempre la risposta sta in uno di questi punti: tema, plugin AMP, configurazione Analytics, configurazione AdSense, cache o CDN.

8. Checklist operativa prima del go-live

Prima di considerare chiusa l’attività, fai questa verifica minima:

• la versione AMP si carica con HTTP 200;
• il markup non contiene script vietati;
• Analytics riceve eventi o pageview;
• AdSense mostra annunci nelle posizioni previste, se il traffico e le policy lo consentono;
• il child theme conserva le modifiche dopo un refresh della cache o un deploy.

Se una di queste voci fallisce, non andare avanti con ulteriori personalizzazioni. Prima correggi il blocco, poi ripeti il test. In un ambiente WordPress con AMP, la disciplina conta più dell’estetica del codice: una configurazione semplice ma valida è molto meglio di un tema ricco di effetti che perde compatibilità alla prima modifica.

La soluzione più solida resta sempre la stessa: child theme per l’aspetto, hook o pannelli del plugin per Analytics e AdSense, validazione AMP dopo ogni passo, e rollback pronto se un blocco pubblicitario o un tag di tracciamento rompe il rendering. Se tieni questo schema, il tema resta gestibile e la parte monetizzazione/misurazione non diventa un punto fragile del sito.