wp-5w

Dashboard di analytics in wp-admin che incrocia i dati già raccolti da WP Statistics (traffico) e da Rank Math Analytics (Google Search Console), senza servizi esterni. Dalla 0.7.0 raccoglie anche le visite da sé, senza cookie e senza salvare IP, in parallelo a WP Statistics (vedi la roadmap): finché non si imposta la data di passaggio, l'interfaccia mostra solo i dati di WP Statistics.

Il nome richiama le 5W (who, what, when, where, why): il valore sta nel collegare le fonti per singolo contenuto, cioè quante visite riceve un articolo, da dove arrivano e con quali ricerche su Google.

Funzionalità

• Tabelle proprie e compatte (wp5w_*), una riga per giorno e dimensione, senza dati personali.
• ETL notturno idempotente, che rielabora gli ultimi 7 giorni per coprire il ritardo di Search Console.
• Import completo all'attivazione e su richiesta.
• Conservazione dello storico: i giorni che WP Statistics e Rank Math cancellano con le loro finestre mobili restano nelle tabelle wp-5w.
• Deduplica delle righe di Search Console, che Rank Math può duplicare quando l'import viene rilanciato.
• Controllo dello schema delle sorgenti: se un aggiornamento cambia le tabelle, la sorgente viene saltata e il motivo compare nella pagina Stato.
• Pagina 5W in wp-admin:
  • Panoramica: KPI con confronto rispetto al periodo precedente, andamento di traffico e Search Console, canali, contenuti più visti con click, impression, CTR e posizione media pesata, opportunità di Search Console in un'unica tabella (quasi in prima pagina, poco cliccate) e pagine su Google, ciascuna con il proprio periodo (ultimi 7, 28, 90 o 180 giorni disponibili).
  • Trend: punteggio da -100 a +100 sulle ultime 4 settimane complete contro le 4 precedenti (visitatori 50%, visibilità su Google 25%, posizione media 25%), per il sito nella Panoramica e per ogni contenuto nelle tabelle.
  • Articoli: ultimi 10 pubblicati e 10 più visti (settimana o mese), con il grafico delle visite degli ultimi 7 giorni; poi «Pagine non trovate» (indirizzi inesistenti visitati, con la provenienza) e «Ricerche interne» (termini cercati sul sito e ricerche senza risultati), entrambi su 7, 30 o 90 giorni.
  • Dettaglio in un modale (clic sul titolo): KPI, andamento, ricerche su Google, canali e siti di provenienza, con periodo selezionabile.
  • Visitatori: «Online adesso» in cima (visitatori degli ultimi 5 minuti e contenuti che guardano, aggiornato ogni 30 secondi solo a scheda visibile), ultimi 7 giorni e ultimi 6 mesi per mese (totali a barre e medie al giorno a linee), quattro box affiancati «Pubblico (paesi)», «Dispositivi», «Browser» e «Sistemi operativi» (ultimi 7, 30 o 90 giorni, con un solo selettore del periodo: 4 colonne da 1280 px, 2 fino a 700 px, 1 sotto), box «Campagne» (UTM di campagna, sorgente e mezzo), provenienze (con i nomi leggibili delle app, per esempio «LinkedIn (app)») e keyword degli ultimi 7 giorni.
  • I box a riga intera si riducono con un toggle, che resta memorizzato nel browser.
  • Stato: confronto della raccolta propria con WP Statistics (giorni completi, differenze, scarti, contenuti), sorgenti, copertura delle tabelle, database dei paesi, ultimo import, avvio manuale e box «Aggiornamenti» (versione installata e ultima, verifica immediata e installazione dalle release di GitHub).
• Raccolta propria (dalla 0.7.0):
  • Tracker di meno di 1,5 KB, in defer, che funziona anche con le pagine in cache: invia la visita a POST /wp5w/v1/hit con sendBeacon. Nessun cookie, nessun localStorage, nessun IP o user agent salvato (il visitatore è un hash che cambia ogni giorno).
  • Esclusioni: Do Not Track, amministratori (o tutti gli utenti collegati), IP e intervalli CIDR, firma errata, oltre 30 visite al minuto per visitatore. Gli scarti si contano per giorno e motivo.
  • Bot e browser automatici (dalla 0.11.0): non si scartano, si segnalano nella colonna bot di wp5w_hits (ua-corto per gli user agent sotto i 16 caratteri, la firma del bot dichiarato, webdriver per navigator.webdriver, '' per le visite normali) e restano nei conteggi: il traffico segnalato si separerà quando si saprà cosa è. Dalla 0.11.0 la raccolta propria può quindi contare più di WP Statistics.
  • Scheda Opzioni per raccolta, utenti, IP, DNT, conservazione e data di passaggio (wp5w_own_since).
  • Le righe si distinguono con la colonna origin (wps o own) nelle tabelle aggregate.
  • Paese, dispositivo, browser e sistema operativo (dalla 0.9.0): il paese si ricava dall'IP con il database DB-IP Lite Country (l'IP non si salva); dispositivo, browser e sistema dallo user agent con regole essenziali, con gli stessi nomi di WP Statistics (smartphone, Mac, GNU/Linux...). Lo user agent non si salva.
  • Canale «Assistenti AI» (dalla 0.10.0): chatgpt.com, perplexity.ai, gemini.google.com, copilot.microsoft.com, claude.ai e simili (elenco Channels::AI) hanno un canale a sé, con la stessa regola sulle due origini, applicata in aggregazione (anche allo storico di WP Statistics).
  • Visite nell'admin (dalla 0.10.0): colonna ordinabile «Visite (30 g)» negli elenchi di articoli e pagine e dato «5W: N visite (30 g)» nella barra di amministrazione sui contenuti singoli, con un clic che apre il dettaglio (admin.php?page=wp5w&tab=posts&detail=<ID>). Solo per chi ha manage_options.
  • 404 e ricerche interne (dalla 0.10.0): solo aggregati giornalieri, senza legame con il visitatore; i termini di ricerca si normalizzano e le email e i numeri lunghi si salvano come «(filtrato)». Le immagini mancanti non compaiono: il server risponde senza passare da WordPress.
• Comandi WP-CLI: wp 5w status, wp 5w etl [--full] [--from=] [--to=] e wp 5w gsc-import <file.jsonl>.
• Collegamento a Search Console dalla scheda Opzioni (dalla 0.12.0): si collega il proprio account Google (OAuth, sola lettura) e il pulsante «Importa da Search Console» scarica dall'API i giorni che mancano (fino a 16 mesi, circa il 60% di query in più di Rank Math), senza toccare i giorni già scaricati; ogni notte, dopo l'ETL, si scaricano da soli quelli nuovi. Il pulsante «Importa da Rank Math» è separato e copia lo storico che Rank Math ha nel database. Vedi Collegare Search Console.
• Recupero dello storico di Search Console da riga di comando con scripts/gsc-backfill.py e wp 5w gsc-import: le credenziali Google restano sul computer, sul server arriva solo il file dei dati. Utile se non vuoi salvare un segreto Google sul server.
• Aggiornamenti dalle release di GitHub: WordPress propone l'aggiornamento come per ogni plugin; dalla 0.11.0 si può anche verificare e installare dal box «Aggiornamenti» della scheda Stato (chi ha update_plugins) o dal link «Verifica aggiornamenti» nella riga del plugin.

Tabelle

Le dimensioni utm_campaign, utm_source e utm_medium di wp5w_dim_daily esistono solo per la raccolta propria (WP Statistics non salva gli UTM). Le cinque tabelle del traffico hanno la colonna origin: wps per le righe importate da WP Statistics, own per quelle della raccolta propria. Le interrogazioni usano wps prima di wp5w_own_since e own da quel giorno in poi (data vuota: solo wps).

La posizione media si calcola sempre come SUM(pos_x_impr) / SUM(impressions), cioè pesata sulle impression come in Search Console.

Database dei paesi

Il paese delle visite proprie si calcola con DB-IP Lite Country, un file .mmdb (lettore maxmind-db/reader, puro PHP) che il plugin scarica da solo:

• Percorso: wp-content/uploads/wp5w/dbip-country-lite.mmdb, con .htaccess e index.php di protezione.
• Aggiornamento: un controllo al giorno (wp5w_geo_update), che scarica il file del mese solo se manca o è di un mese precedente (prima il mese corrente, poi il precedente). Il file si controlla (integrità del gzip, dimensione, metadati, ricerca di prova) e si sostituisce in modo atomico; se qualcosa va storto resta quello vecchio. Lo stato è nella scheda Stato.
• Licenza e attribuzione: i dati sono IP Geolocation by DB-IP, con licenza CC BY 4.0: il link è in fondo alla pagina 5W e nella card «Database dei paesi».
• Il file si cancella sempre alla disinstallazione (è una cache che si riscarica, non uno storico).

Collegare Search Console

Ogni sito usa il proprio client OAuth di Google, creato una volta nella Google Cloud Console (nessun dato passa da server di terzi). La scheda Opzioni › Search Console mostra i passaggi con i link e l'indirizzo da copiare:

1. Nella Google Cloud Console crea un progetto e abilita la Google Search Console API.
2. In Google Auth Platform configura la schermata di consenso (tipo «Esterno») e pubblica l'app «In produzione»: in «Test» il collegamento scade dopo 7 giorni. Google mostra l'avviso «app non verificata» (Avanzate › Continua): è normale, l'app è tua e chiede solo la sola lettura (webmasters.readonly).
3. Crea un client OAuth di tipo Applicazione web e come «URI di reindirizzamento autorizzato» incolla l'indirizzo mostrato nella scheda (…/wp-admin/admin-post.php?action=wp5w_gsc_oauth).
4. Copia ID client e segreto nella scheda, premi Collega Google, scegli la proprietà (se ne trova una per il sito la sceglie da sola) e premi Importa da Search Console.

Il segreto e il token di rinnovo si salvano cifrati (sodium, chiave derivata dalle salt di wp-config.php: se cambiano, il collegamento va rifatto). Scollega Google revoca il token. L'import va a lotti di 30 giorni e riprende da dove si era fermato; con una proprietà di dominio (sc-domain:) si tengono solo le pagine dell'host del sito.

Requisiti

• WordPress 6.5 o superiore, PHP 8.3 o superiore.
• WP Statistics 14.x e/o Rank Math con il modulo Analytics collegato a Search Console. Funziona anche con una sola delle due sorgenti.

Installazione

Scarica lo zip dall'ultima release e caricalo da Plugin › Aggiungi nuovo, oppure:

wp plugin install https://github.com/mavidasnc/wp-5w/releases/latest/download/wp-5w-X.Y.Z.zip --activate
wp 5w etl --full

All'attivazione l'import completo parte da solo dopo un minuto; con WP-CLI lo si lancia subito.

Disinstallazione

Le tabelle wp5w_* sono spesso l'unica copia dello storico, quindi la disinstallazione non le cancella. Per eliminarle (comprese wp5w_hits e wp5w_discards) e togliere le opzioni wp5w_settings, wp5w_own_since, wp5w_gsc_state, wp5w_gsc_empty_days e wp5w_rankmath_state, definisci WP5W_DELETE_DATA a true in wp-config.php prima di disinstallare. Client secret e token di Google (opzione wp5w_gsc) si tolgono sempre, ma senza revocare il token: prima di disinstallare usa Scollega Google. L'opzione wp5w_daily_salt e il database dei paesi (opzione wp5w_geo, cartella uploads/wp5w/) si tolgono sempre.

Sviluppo

composer install
npm install --ignore-scripts
npm run build          # build dell'admin React
composer ci            # PHPCS, PHPStan, PHPUnit
npm run check          # build + controllo dei file compilati

Il flusso dei test con wp-env è in CLAUDE.md. L'analisi che ha portato al progetto è in docs/.