# 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…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-06-29
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfgscconnect/index.md), [en](https://www.datafirefly.com/en/documentation/dfgscconnect/index.md), [es](https://www.datafirefly.com/es/documentation/dfgscconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfgscconnect/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfgscconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfgscconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Indice:
**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.
**Multinegozio nativo.** Il modulo è multinegozio. Ogni negozio archivia il proprio token OAuth, la propria proprietà Search Console e la propria cronologia di metriche. Puoi connettere un negozio senza influire sugli altri.
### 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](https://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**.
**L'URL di reindirizzamento deve essere strettamente identico.** Compresi protocollo (`https`), sottodominio (`www` o no) e assenza di slash finale. Una sola differenza e Google blocca la connessione con `redirect_uri_mismatch`.
### 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.
**Latenza Search Console.** Google fornisce i dati di Search Analytics con circa 48 ore di ritardo. Se ti sei appena connesso, alcune metriche di ieri o l'altro ieri non saranno ancora disponibili. È normale. Il modulo ne tiene conto automaticamente nei calcoli di cali (finestra scorrevole con sfasamento di 2 giorni).
## 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
**Deindicizzazione rilevata → avviso automatico.** Se il verdetto è FAIL o NEUTRAL, o lo stato di copertura è DEINDEXED o INDEXING_NOT_ALLOWED, viene generato un avviso HIGH automaticamente con il motivo restituito da Google.
## 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"
```
**Compatibile con hosting condiviso.** Nessuna dipendenza da Redis, BullMQ, worker persistente o PHP-FPM dedicato. L'endpoint cron è un semplice URL HTTPS protetto da token. Funziona nativamente su o2switch, OVH condiviso e qualsiasi hosting Linux standard.
## 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._