GSC Connect — Documentazione

GSC Connect porta tutta la potenza di Google Search Console direttamente nel back-office PrestaShop: connessione OAuth con un clic, invio di sitemap, ispezione URL in massa, report di clic e posizione per prodotto e categoria, avvisi automatici di calo e deindicizzazione. Questa guida copre l’installazione, la configurazione OAuth con Google, la prima sincronizzazione, la pianificazione cron, la lettura dei report, la gestione degli errori comuni e l’architettura interna.

Installazione

Il modulo si installa come qualsiasi modulo PrestaShop standard: nessuna dipendenza Composer, nessun worker persistente, nessun servizio esterno oltre a Google.

1. Scarica dfgscconnect.zip dal tuo account DataFirefly (link di download ricevuto dopo l’acquisto).
2. Back-office → Moduli → Gestore moduli → Carica un modulo.
3. Trascina e rilascia lo ZIP. PrestaShop installa automaticamente le 8 tabelle dfgsc_*, le schede del menu e gli hook associati.
4. Fai clic su Configura sulla scheda del modulo.

Requisiti

• PrestaShop 8.0.0 a 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 o 8.3
• MySQL 5.6+ o MariaDB 10.3+
• Estensione PHP curl abilitata (di default su tutti gli hosting)
• Un account Google che ha già accesso proprietario o proprietario delegato alla proprietà Search Console del tuo negozio

Configurazione OAuth con Google

Il modulo usa OAuth 2.0 per accedere a Search Console a nome del proprietario del negozio. Questa configurazione si fa una sola volta e richiede circa 5 minuti. Nessun service account richiesto: l’autenticazione usa direttamente l’account Google che ha già accesso alla tua proprietà Search Console.

Passo 1 — Crea un progetto Google Cloud

1. Vai a console.cloud.google.com con l’account Google che possiede l’accesso a Search Console.
2. Fai clic sul selettore di progetto in alto, poi su Nuovo progetto.
3. Nominalo ad esempio prestashop-gsc e crealo.
4. Seleziona questo nuovo progetto una volta creato.

Passo 2 — Attiva l’API Search Console

1. Menu → API e servizi → Libreria.
2. Cerca Google Search Console API.
3. Fai clic e poi su Abilita.

Passo 3 — Configura la schermata di consenso

1. Menu → API e servizi → Schermata di consenso OAuth.
2. Scegli External se il tuo account Google non fa parte di un’organizzazione Google Workspace, altrimenti Internal.
3. Compila il nome dell’applicazione (ad esempio GSC Connect), la tua email di supporto e il dominio del tuo negozio.
4. Nella schermata Scopes, aggiungi lo scope https://www.googleapis.com/auth/webmasters (lettura/scrittura Search Console).
5. Nella schermata Test users, aggiungi il tuo indirizzo Google. Finché la schermata resta in modalità test, è sufficiente per uso privato: non è necessario inviare l’app a verifica Google.

Passo 4 — Crea le credenziali OAuth

1. Menu → API e servizi → Credenziali.
2. Crea credenziali → ID client OAuth.
3. Tipo di applicazione: Applicazione web.
4. Nome: GSC Connect (libero).
5. In Origini JavaScript autorizzate, aggiungi il dominio del tuo negozio con HTTPS: https://il-tuo-negozio.it.
6. In URI di reindirizzamento autorizzato, incolla l’URL esatto mostrato nella configurazione del modulo PrestaShop (riquadro URL di reindirizzamento OAuth).
7. Fai clic su Crea. Google mostra un Client ID e un Client Secret.

Passo 5 — Inserisci le credenziali in PrestaShop

1. Back-office → modulo → Configura.
2. Incolla il Client ID e il Client Secret.
3. Salva il modulo. Appare un pulsante Connetti a Google.
4. Fai clic. Vieni reindirizzato alla pagina di consenso Google.
5. Approva i permessi, vieni reindirizzato al back-office PrestaShop.
6. L’elenco delle tue proprietà Search Console viene recuperato automaticamente: il modulo seleziona per impostazione predefinita quella che corrisponde al dominio del tuo negozio.

Primo avvio

Una volta stabilita la connessione OAuth, avvia la prima sincronizzazione per recuperare i tuoi dati:

1. Scheda Dashboard. La proprietà predefinita è già selezionata.
2. Fai clic su Sincronizza ora. Il modulo recupera gli ultimi 28 giorni di dati (clic, impressioni, CTR, posizione) a livello di pagina e query. Conta da 30 secondi a 2 minuti a seconda del volume del tuo catalogo.
3. Scheda Sitemap. I candidati vengono rilevati automaticamente (/sitemap.xml radice + pattern *_sitemap.xml generato dal modulo gsitemap di PrestaShop). Fai clic su Invia accanto a ciascun sitemap rilevante.
4. Scheda Ispezione. Fai clic su Accoda tutti i prodotti attivi. La coda si riempie istantaneamente. L’elaborazione reale avviene tramite cron rispettando la quota Google di 2000 ispezioni al giorno.

Dashboard

La dashboard raggruppa 8 KPI su 28 giorni:

• Clic — totale di clic organici nella finestra
• Impressioni — totale di visualizzazioni nella SERP
• CTR medio — percentuale di clic rispetto alle impressioni
• Posizione media — posizione media ponderata su tutte le query
• Avvisi non letti — numero di avvisi aperti da gestire
• Pagine non indicizzate — numero di pagine ispezionate con verdetto FAIL o NEUTRAL di Google
• Quota di oggi — chiamate API URL Inspection consumate sulla quota giornaliera
• Ultima sincronizzazione — data e ora dell’ultimo passaggio cron sync

Sotto i KPI, un grafico di andamento a 28 giorni mostra i clic (linea piena) e le impressioni (linea tratteggiata su asse secondario). Chart.js è impacchettato in locale, nessuna dipendenza CDN viene caricata.

A destra, il Top 10 prodotti e il Top 10 categorie classificano le tue pagine per clic con posizione media e CTR. La risoluzione URL → entità usa il routing nativo PrestaShop: pattern id-slug per i prodotti, link_rewrite per le categorie, cms_lang per le pagine CMS.

Report di clic e posizione

La scheda Report offre tre viste dettagliate: Prodotti, Categorie, Query. Ogni vista accetta un lookback configurabile: 7 / 14 / 28 / 90 giorni.

Per ogni riga ottieni clic, impressioni, CTR e posizione media. Fai clic su qualsiasi intestazione di colonna per ordinare (lato client, istantaneo). L’esportazione CSV produce un file UTF-8 con BOM e separatore punto e virgola (nativamente compatibile Excel), fino a 5000 righe per export.

Confronto tra finestre

Per ogni prodotto o categoria elencato, il report mostra anche la variazione rispetto alla finestra precedente di pari durata. Un calo significativo di posizione appare in rosso, un miglioramento in verde.

Sitemap

La scheda Sitemap rileva automaticamente i candidati sul tuo negozio:

• https://il-tuo-negozio.it/sitemap.xml — sitemap radice
• https://il-tuo-negozio.it/sitemap_index.xml — indice di sitemap
• Pattern *_sitemap.xml alla radice — generato dal modulo gsitemap di PrestaShop, un file per negozio e per lingua

Invia con un clic. Il modulo poi monitora per te:

• Il numero di URL inviate (dichiarate dal tuo sitemap)
• Il numero di URL realmente indicizzate (riportate da Google)
• Il numero di errori rilevati da Google
• La data dell’ultimo download da parte di Googlebot

Se Google rileva errori su un sitemap, viene generato un avviso automatico: severità HIGH se ≥ 10 errori, altrimenti MEDIUM.

Ispezione URL in massa

L’API URL Inspection di Google è limitata a 2000 chiamate al giorno per proprietà. GSC Connect gestisce questo limite tramite una coda con retry automatico.

Azioni disponibili

• Accoda tutti i prodotti attivi — aggiunge tutti i prodotti con visibilità both, search o catalog
• Accoda tutte le categorie — aggiunge tutte le categorie attive (la radice è esclusa)
• Re-ispeziona le pagine modificate — aggiunge solo le entità contrassegnate come obsolete dagli hook actionProductUpdate e actionCategoryUpdate
• Elabora la coda ora — per i test, senza attendere il cron
• Ispeziona un URL ad-hoc — per validare una correzione immediata su una pagina specifica

Dati registrati

Per ogni URL ispezionato, il modulo registra:

• Il verdetto globale di Google: PASS, PARTIAL, FAIL o NEUTRAL
• Lo stato di copertura (Indexed, Discovered, Crawled but not indexed, ecc.)
• Lo stato robots.txt e l’indicizzabilità dichiarata
• I rich result rilevati (Product, Breadcrumb, Review, ecc.)
• Lo stato AMP e la conformità mobile-friendly
• Il sitemap di riferimento e gli URL di riferimento
• La data dell’ultimo crawl da parte di Googlebot

Avvisi e cali

Il modulo gestisce automaticamente tre famiglie di avvisi:

Cali di posizione

Rileva un calo significativo di posizione su una pagina già ben posizionata. Default: calo di 5 posizioni o più su una pagina posizionata ≤ 50. Soglia regolabile nelle impostazioni (DFGSC_DROP_POS).

Cali di clic

Rileva un calo significativo di clic su una pagina che generava un volume minimo. Default: calo del 30 % con un minimo di 5 clic nella finestra precedente. Soglie regolabili nelle impostazioni (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Deindicizzazioni

Generata automaticamente quando un URL ispezionato restituisce un verdetto FAIL o NEUTRAL, o uno stato di copertura DEINDEXED / INDEXING_NOT_ALLOWED.

Meccanica di confronto

Il confronto cali si fa su una finestra scorrevole di 7 giorni contro i 7 giorni precedenti, con uno sfasamento di 2 giorni per rispettare la latenza di Search Console. Il modulo confronta D-9..D-2 con D-16..D-9.

Deduplicazione 24h

Lo stesso avviso (stessa pagina, stesso tipo) si attiva solo una volta ogni 24h per evitare rumore, anche se il cron gira ogni ora.

Notifiche e-mail

Gli avvisi possono essere inviati per e-mail come digest HTML raggruppato per severità, in francese o inglese. Attivali dalle impostazioni e imposta l’indirizzo del destinatario.

Cron e pianificazione

Tutte le attività in background passano per un singolo endpoint protetto da token, visibile nella pagina di configurazione:

https://il-tuo-negozio.it/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Pianificalo ogni 1-6 ore dal pannello cron del tuo hosting (cPanel, Plesk, o2switch, OVH). Esempio crontab:

0 */2 * * * curl -fsS "https://il-tuo-negozio.it/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX" > /dev/null 2>&1

Attività eseguite

Per impostazione predefinita, l’endpoint esegue ogni attività. Puoi filtrarne alcune con il parametro &tasks=:

Attività	Azione
sync	Recupera nuovi dati Search Analytics (lookback configurabile)
inspect	Elabora la coda di ispezione URL rispettando la quota
sitemaps	Aggiorna lo stato delle sitemap inviate
drops	Rileva cali di posizione e clic
notify	Invia il digest degli avvisi per e-mail
prune	Purga le voci di coda completate e i contatori di quota vecchi

Esempio per sincronizzare solo le metriche senza toccare l’ispezione:

curl "https://il-tuo-negozio.it/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX&tasks=sync,drops,notify"

Riferimento configurazione

Tutte le opzioni sono nella pagina Configura del modulo:

Opzione	Chiave	Default
Client ID Google	DFGSC_CLIENT_ID	(da compilare)
Client Secret Google	DFGSC_CLIENT_SECRET	(da compilare)
Lookback sincronizzazione (giorni)	DFGSC_LOOKBACK_DAYS	28
Quota giornaliera ispezione URL	DFGSC_DAILY_QUOTA	2000
Soglia calo posizione	DFGSC_DROP_POS	5
Soglia calo clic (%)	DFGSC_DROP_CLICKS	30
Clic minimi per rilevare calo	DFGSC_DROP_MIN_CLICKS	5
Notifiche e-mail abilitate	DFGSC_ALERT_ENABLED	sì
Indirizzo destinatario avvisi	DFGSC_ALERT_EMAIL	e-mail admin
Token cron	DFGSC_CRON_TOKEN	auto-generato

Quote e limiti API Google

L’API Search Console è gratuita ma soggetta a quote Google:

• URL Inspection: 2000 chiamate al giorno per proprietà, 600 al minuto (hard limit Google, non negoziabile)
• Search Analytics: 25000 righe per chiamata, ~1200 chiamate al minuto, 30000 al giorno (soft cap)
• Sitemap: 5000 chiamate al giorno

Il modulo registra tutte le chiamate per endpoint e per giorno nella tabella dfgsc_quota. La coda di ispezione si ferma in modo pulito quando viene raggiunta la quota configurata, generando un avviso di severità MEDIUM. I contatori vengono purgati automaticamente dopo 30 giorni dall’attività prune.

Architettura e dati

Il modulo segue un’architettura PSR-4 classica sotto il namespace DataFirefly/GscConnect/, con un autoloader proprietario fornito in vendor/autoload.php. Nessuna dipendenza Composer. Nessuna dipendenza esterna: le chiamate API Google avvengono in cURL nativo con verifica SSL.

Livelli

• Api/ — client HTTP (GoogleOAuth, SearchConsoleClient)
• Model/ — repository di accesso al database (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services/ — orchestrazione (MetricsSync, Inspection, Sitemap, Alert)

Tabelle create

Tabella	Ruolo
dfgsc_token	Refresh token OAuth + scadenza per negozio
dfgsc_site	Proprietà Search Console conosciute (per negozio, con la predefinita)
dfgsc_metric	Righe Search Analytics (per giorno, per pagina, opzionalmente per query)
dfgsc_inspection	Cache locale delle ispezioni URL con il loro verdetto completo
dfgsc_sitemap	Stato delle sitemap inviate (URL, inviate, indicizzate, errori, ultimo download)
dfgsc_alert	Avvisi generati (tipo, severità, pagina, delta, stato)
dfgsc_queue	Coda di ispezione con stati pending/processing/done/failed
dfgsc_quota	Contatori di chiamate API per endpoint e per giorno

Hook utilizzati

• actionAdminControllerSetMedia — caricamento asset back-office
• displayBackOfficeHeader — riservato per notifiche future
• actionProductUpdate / actionCategoryUpdate — invalidazione cache ispezione
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — purga ispezioni orfane

Sicurezza

• Token CSRF di stato basato su cookie nel flusso OAuth
• Validazione hash_equals sul token cron
• Refresh token memorizzato in DB, mai loggato
• Access token mai persistito: rigenerato a richiesta dal refresh token e tenuto in memoria per la durata della richiesta
• File index.php anti-listing in tutte le sottodirectory
• Escape sistematico tramite Tools::safeOutput su tutte le uscite dei template

Risoluzione problemi

Il pulsante “Connetti a Google” non appare

Verifica che Client ID e Client Secret siano effettivamente salvati. Salva il form, poi ricarica la pagina di configurazione.

La schermata Google mostra redirect_uri_mismatch

L’URI di reindirizzamento in Google Cloud deve essere strettamente identica a quella mostrata nella configurazione del modulo: stesso protocollo (https), stesso sottodominio (www o no), stesso percorso, senza slash finale. Copia e incolla senza modificare.

La sincronizzazione non restituisce dati

Verifica tre punti: (1) la proprietà selezionata è effettivamente il tuo negozio; (2) ha almeno 72 ore di cronologia in Search Console (Google fornisce con ~48 h di latenza); (3) l’account Google connesso ha accesso proprietario o proprietario delegato a questa proprietà.

Le ispezioni non avvengono

Verifica che il cron sia pianificato e venga eseguito. Verifica poi la quota del giorno: se hai consumato le 2000 chiamate Google, la coda è in pausa fino al giorno successivo. Puoi forzare manualmente tramite il pulsante Elabora la coda ora.

Gli avvisi e-mail non arrivano

Verifica che l’indirizzo sia valido, che la configurazione SMTP di PrestaShop funzioni (testala con un’e-mail di benvenuto ad esempio), e che le notifiche siano abilitate nella configurazione del modulo.

Errore 401 o 403 sulle chiamate Search Console

Il refresh token è stato probabilmente revocato lato Google (cambio password, sicurezza account, o consenso scaduto). Disconnetti e riconnetti il negozio dalla configurazione.

Errore Quota Exhausted (429)

La quota Google della proprietà è raggiunta. È limitata a 2000 ispezioni al giorno da Google, indipendentemente dal numero di moduli o strumenti che interrogano la proprietà. La coda riprende automaticamente il giorno successivo.

Changelog

Consulta il file CHANGELOG.md incluso nello ZIP del modulo per l’elenco completo delle modifiche per versione.

---

Per qualsiasi domanda non coperta qui, contatta il supporto DataFirefly su support@datafirefly.com.