# Predictive SEO — Documentazione completa

> Panoramica DataFirefly Predictive SEO connette il suo PrestaShop a Google Search Console, applica un motore di previsione ML embedded sullo storico di ricerca e identifica automaticamente i picchi stagionali in…

- Pagina: <https://www.datafirefly.com/it/documentation/dfpredictiveseo/>
- Lingua: it
- Aggiornato il: 2026-06-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfpredictiveseo/index.md), [en](https://www.datafirefly.com/en/documentation/dfpredictiveseo/index.md), [es](https://www.datafirefly.com/es/documentation/dfpredictiveseo/index.md), [de](https://www.datafirefly.com/de/documentation/dfpredictiveseo/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpredictiveseo/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfpredictiveseo/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpredictiveseo/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## Panoramica

DataFirefly Predictive SEO connette il suo PrestaShop a Google Search Console, applica un motore di previsione ML embedded sullo storico di ricerca e identifica automaticamente i picchi stagionali in arrivo. Per ogni opportunità rilevata, può generare in un clic un brief di contenuto strutturato via Mistral, OpenAI o Claude.

**Da ricordare:** Predictive SEO non misura ciò che è già accaduto — proietta ciò che sta per accadere. Il modulo lavora in pura anticipazione: lei pubblica il contenuto due settimane prima del picco di ricerca, conquista la posizione prima che arrivi l'onda.

### Prerequisiti

- PrestaShop 8.0+ o PrestaShop 9.x
- PHP 8.1 minimo
- MySQL 5.7+ o MariaDB 10.3+
- Un account Google con accesso alla proprietà Search Console dello store
- Una chiave API di un provider IA (Mistral, OpenAI o Anthropic — Mistral di default, circa 0,002 € per brief)
- Almeno 60-90 giorni di storico GSC per previsioni affidabili

## Installazione

### Installazione dal ZIP

1. Scarichi il file `dfpredictiveseo.zip` dalla sua area cliente DataFirefly.
2. Nel back-office PrestaShop, vada in **Moduli → Gestore moduli**.
3. Clicchi su **Carica un modulo** e rilasci il ZIP.
4. Il modulo si installa automaticamente, crea le 7 tabelle `dfpseo_*`, registra le 6 tab sotto IMPROVE e genera un token cron unico.
5. Una volta installato, trovi il modulo nel menu **Migliora → Predictive SEO**.

**Aggiornamento:** Per un aggiornamento futuro, il caricamento di un nuovo ZIP sovrascrive i file ed esegue automaticamente gli script `upgrade-X.Y.Z.php`. I dati e la configurazione vengono preservati.

### Schema database

L'installazione crea 7 tabelle con il prefisso `dfpseo_`:

- `dfpseo_keyword` — keyword tracciate da GSC
- `dfpseo_history` — storico giornaliero (impressioni, clic, CTR, posizione)
- `dfpseo_forecast` — previsioni giornaliere con intervalli di confidenza
- `dfpseo_opportunity` — opportunità stagionali rilevate
- `dfpseo_recommendation` — brief di contenuto generati da IA
- `dfpseo_seasonality` — indici stagionali (giorno-settimana × mese) per keyword
- `dfpseo_sync_log` — registro delle sincronizzazioni GSC

## Configurazione Google Search Console

Il modulo utilizza il protocollo OAuth2 standard. Lei crea un OAuth Client in Google Cloud, incolla le credenziali nelle impostazioni e lancia il flusso di autorizzazione dal pulsante Connetti.

### Passo 1 — Creare un progetto Google Cloud

1. Vada su [console.cloud.google.com](https://console.cloud.google.com/) e acceda con l'account Google che ha accesso alla sua proprietà Search Console.
2. Clicchi sul selettore di progetto in alto a sinistra, poi su **Nuovo progetto**.
3. Lo nomini ad esempio _DataFirefly Predictive SEO_ e lo crei.

### Passo 2 — Attivare l'API Search Console

1. Nel menu di sinistra, vada in **API e Servizi → Libreria**.
2. Cerchi _Search Console API_ e clicchi su **Attiva**.

### Passo 3 — Configurare la schermata di consenso OAuth

1. Vada in **API e Servizi → Schermata di consenso OAuth**.
2. Tipo di utente: **Esterno**.
3. Compili nome dell'app, email di supporto, dominio autorizzato (il suo store).
4. In **Ambiti**, aggiunga `https://www.googleapis.com/auth/webmasters.readonly` (sola lettura Search Console).
5. In modalità test, aggiunga la sua email negli **Utenti di test**. Potrà passare in produzione in seguito senza modifiche al modulo.

### Passo 4 — Creare il Client OAuth

1. Vada in **API e Servizi → Credenziali**.
2. Clicchi su **Crea credenziali → ID client OAuth**.
3. Tipo di applicazione: **Applicazione web**.
4. Nome: libero (ad esempio _Predictive SEO Produzione_).
5. URI di reindirizzamento autorizzato: copi l'URI visualizzato nelle impostazioni del modulo (**Improve → Predictive SEO → Impostazioni → Google Search Console → URI di reindirizzamento**). Formato: `https://il-suo-store.com/module/dfpredictiveseo/settings/oauth_callback`.
6. Clicchi su **Crea** — Google mostra il `client_id` e il `client_secret`.

### Passo 5 — Connettere il modulo

1. Nelle impostazioni Predictive SEO, incolli il `client_id` e il `client_secret`.
2. Salvi.
3. Clicchi su **Connetti a Google Search Console**.
4. Viene reindirizzato alla pagina di consenso Google. Autorizzi l'accesso di sola lettura.
5. Tornato nel back-office, il modulo ha memorizzato il `refresh_token` cifrato ed è pronto a sincronizzare.
6. Selezioni quindi la **proprietà Search Console** da tracciare nel dropdown (il modulo la rileva automaticamente dopo la connessione).

**Attenzione:** L'URI di reindirizzamento deve essere **identico carattere per carattere** tra Google Cloud e il modulo. Una differenza di protocollo (http/https), di slash finale o di sottodominio provoca un errore `redirect_uri_mismatch`.

## Configurazione del provider IA

Il modulo supporta 3 provider IA per generare i brief di contenuto. Ne basta uno, e lei fornisce la propria chiave API del provider scelto — DataFirefly non preleva alcuna commissione sull'uso.

### Mistral (default, consigliato)

- Modello: `mistral-small-latest`
- Costo indicativo: circa 0,002 € per brief generato
- Creare la chiave: [console.mistral.ai](https://console.mistral.ai/) → API Keys
- Incollare la chiave in **Impostazioni → Provider IA → Chiave API Mistral**

### OpenAI

- Modello: `gpt-4o-mini`
- Costo indicativo: circa 0,005 € per brief
- Creare la chiave: [platform.openai.com](https://platform.openai.com/api-keys) → API keys
- Incollare la chiave in **Impostazioni → Provider IA → Chiave API OpenAI**

### Anthropic (Claude)

- Modello: `claude-3-5-haiku-latest`
- Costo indicativo: circa 0,004 € per brief
- Creare la chiave: [console.anthropic.com](https://console.anthropic.com/) → API Keys
- Incollare la chiave in **Impostazioni → Provider IA → Chiave API Anthropic**

Selezioni quindi il provider attivo nel dropdown **Provider IA attivo**. Se cambia provider, i brief già generati non vengono rigenerati automaticamente.

## Sincronizzazione dei dati

### Prima sincronizzazione

Una volta stabilita la connessione GSC, lanci una prima sincronizzazione manuale: **Impostazioni → Avvia sincronizzazione**. Il modulo recupera lo storico degli ultimi 90 giorni per la proprietà selezionata — fino a 250 000 righe per sincronizzazione, con le dimensioni _data × query × pagina_. La prima sincronizzazione può richiedere da 30 secondi a 2 minuti a seconda del volume.

### Cron giornaliero

Per le sincronizzazioni automatiche, configuri un cron giornaliero (consigliato: presto al mattino, 4-6 ore di Parigi) che richiami l'endpoint protetto del modulo.

L'URL esatto e il token sono visualizzati in **Impostazioni → Cron**. Formato generico:

```
https://il-suo-store.com/module/dfpredictiveseo/cron/sync?token=IL_SUO_TOKEN_GENERATO
```

Esempio di riga crontab (cron Unix):

```
0 5 * * * curl -s "https://il-suo-store.com/module/dfpredictiveseo/cron/sync?token=IL_SUO_TOKEN" > /dev/null 2>&1
```

**Consiglio:** Il token viene generato casualmente all'installazione e memorizzato nella tabella di configurazione di PrestaShop (`DFPSEO_CRON_TOKEN`). Se viene compromesso, può rigenerarlo da **Impostazioni → Rigenera token cron**.

### Pipeline di una sincronizzazione

Ogni sincronizzazione esegue in sequenza:

1. Pull GSC sugli ultimi 90 giorni scorrevoli (dimensioni data/query/pagina)
2. Inserimento/aggiornamento in `dfpseo_keyword` e `dfpseo_history`
3. Ricalcolo degli indici stagionali (per keyword con storico sufficiente)
4. Generazione dei forecast sull'orizzonte configurato
5. Rilevamento delle opportunità sulla finestra futura
6. Log in `dfpseo_sync_log`

## Dashboard

La dashboard (**Improve → Predictive SEO → Cruscotto**) raggruppa gli indicatori chiave:

- **4 KPI card**: keyword tracciate, opportunità in arrivo, clic previsti su 14 giorni, ultima sync GSC
- **Grafico principale**: curva aggregata storico (90 giorni) + forecast (orizzonte configurato, 30 giorni di default), con banda di confidenza al 95%
- **Top opportunità**: i 10 prossimi picchi stagionali ordinati per punteggio
- **Registro sync**: le 5 ultime sincronizzazioni con il loro stato

### Stato della connessione

Due badge in alto nella dashboard indicano lo stato delle integrazioni: **GSC connesso** (verde/rosso) e **Provider IA configurato** (verde/rosso). Se uno dei due è rosso, segua il link diretto alle impostazioni corrispondenti.

## Keyword & previsioni

### Lista delle keyword

La tab **Keyword** mostra la griglia nativa PrestaShop con tutte le query sincronizzate. Colonne: query, pagina di atterraggio, impressioni 30 g, clic 30 g, CTR, posizione media, ultimo aggiornamento. Può filtrare, ordinare ed esportare.

### Vista dettagliata per keyword

Un clic su una keyword apre la sua scheda:

- Curva individuale storico + forecast personale
- Intervallo di confidenza 95% attorno alla previsione
- Heatmap stagionale 12 × 7 (mese × giorno-settimana)
- Indici stagionali calcolati
- Lista delle opportunità collegate a questa keyword

### Heatmap di stagionalità

La heatmap visualizza gli indici stagionali moltiplicativi. Lettura:

- Cella a 1,00 → traffico medio su questa combinazione mese × giorno
- Cella a 1,50 → traffico 50% sopra la media (picco stagionale)
- Cella a 0,60 → traffico 40% sotto la media (valle)

Le celle sono colorate dal blu pallido (valle) al blu profondo e rosso-arancio (picco). Una sola occhiata basta per individuare le settimane da sfruttare.

## Opportunità stagionali

### Rilevamento automatico

Un'opportunità viene rilevata quando, su una finestra futura di 14 giorni (configurabile via `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS`):

- La previsione supera la baseline della keyword × 1,25 (**soglia di picco**)
- E l'indice stagionale della combinazione mese × giorno è superiore a 1,10

I picchi contigui (gap ≤ 2 giorni) sono raggruppati in una sola opportunità che copre la finestra completa.

### Punteggio di opportunità

Il punteggio combina tre fattori:

```
score = clic_attesi × lift × confidenza
```

- `clic_attesi`: somma dei clic previsti sulla finestra
- `lift`: rapporto picco / baseline
- `confidenza`: ampiezza dell'intervallo di previsione (più stretto, più alto è il punteggio)

Un punteggio > 80 indica un'opportunità ad alto potenziale e forte segnale stagionale. Un punteggio 40-80 indica un'opportunità moderata. Sotto 40, il segnale è troppo debole o troppo incerto per giustificare un'azione prioritaria.

### Workflow di opportunità

Ogni opportunità ha uno stato:

- **Nuova** — appena rilevata, in attesa di decisione
- **In corso** — è stato generato un brief, in lavoro redazionale
- **Completata** — contenuto pubblicato, opportunità sfruttata
- **Ignorata** — decisione di non trattare (falso positivo, fuori strategia)

## Raccomandazioni IA

### Generare un brief

Da qualsiasi opportunità, clicchi su **Genera il brief**. Il modulo invia una richiesta al provider IA attivo con il contesto della keyword (volume, stagionalità, posizione attuale, pagina interessata) e riceve un brief JSON strutturato contenente:

- **summary** — riassunto strategico del brief
- **meta_description** — meta description SEO pronta da incollare (150-160 caratteri)
- **search_intent** — intento di ricerca dominante (informazionale / transazionale / navigazionale / commerciale)
- **outline** — piano dettagliato h1/h2/h3 dell'articolo o della pagina
- **keywords_to_include** — keyword semantiche da includere
- **internal_links** — suggerimenti di link interni verso altre pagine del sito
- **rationale** — giustificazione strategica della raccomandazione

La generazione richiede da 1 a 3 secondi a seconda del provider.

### Workflow di approvazione

Ogni brief passa attraverso gli stati:

1. **Pending** — generato, in attesa di revisione
2. **Approved** — validato per la redazione
3. **Published** — contenuto online (da contrassegnare manualmente)
4. **Rejected** — rifiutato (brief di scarsa qualità o fuori tema)
5. **Draft** — in modifica

Il workflow le permette di mantenere una traccia chiara di ciò che è stato trattato.

## Architettura tecnica

### Stack

- Architettura PSR-4, namespace `DfPredictiveSeo` → `src/`
- Controller Symfony che estendono `FrameworkBundleAdminController`
- Repository Doctrine DBAL (nessun ObjectModel)
- GSC acceduta in REST diretto via cURL + OAuth2 (nessun `google/apiclient`, per rimanere leggero)
- Nessuna dipendenza Composer obbligatoria all'installazione (autoloader PSR-4 incorporato)

### Pipeline ML

1. **Decomposizione stagionale moltiplicativa**: indici giorno-settimana e mese calcolati tramite media mobile centrata 28 giorni e media troncata 10%
2. **Regressione OLS** su `log(impressioni+1)` per modellare il trend log-lineare
3. **Forecast**: `exp(prediction_log) × indice_stagionale_giorno × indice_stagionale_mese`
4. **Intervalli 95%**: approssimazione Student sull'errore residuo della regressione, allargamento progressivo con l'orizzonte

### Endpoint cron

L'endpoint è pubblico ma protetto da token. Esempio in PHP per chiamate programmatiche:

```
$token = 'il_suo_token_cron';
$url = 'https://il-suo-store.com/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = numero di keyword aggiornate
// $data['opportunities_detected'] = numero di opportunità appena rilevate
```

### Variabili di configurazione

Il modulo memorizza 18 chiavi di configurazione nella tabella `ps_configuration`:

- `DFPSEO_GSC_CLIENT_ID`, `DFPSEO_GSC_CLIENT_SECRET`, `DFPSEO_GSC_REFRESH_TOKEN` (cifrato), `DFPSEO_GSC_PROPERTY`
- `DFPSEO_AI_PROVIDER`, `DFPSEO_AI_MISTRAL_KEY`, `DFPSEO_AI_OPENAI_KEY`, `DFPSEO_AI_ANTHROPIC_KEY`
- `DFPSEO_FORECAST_HORIZON_DAYS` (default: 30)
- `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS` (default: 14)
- `DFPSEO_PEAK_THRESHOLD` (default: 1.25)
- `DFPSEO_SEASONAL_THRESHOLD` (default: 1.10)
- `DFPSEO_CRON_TOKEN` (generato all'installazione)
- `DFPSEO_LAST_SYNC`, `DFPSEO_LAST_FORECAST`

## Risoluzione dei problemi

### Errore `redirect_uri_mismatch` al momento della connessione GSC

L'URI di reindirizzamento configurato in Google Cloud non corrisponde esattamente a quello atteso dal modulo. Verifichi:

- Protocollo: `https://` e non `http://`
- Nessuno slash finale: `...oauth_callback` e non `...oauth_callback/`
- Sottodominio: `www.` o no a seconda del suo store, deve corrispondere

### La sync GSC non restituisce alcuna keyword

- Verifichi che la proprietà selezionata nelle impostazioni sia effettivamente quella che riceve traffico SEO (e non una proprietà di dominio vuota)
- Verifichi che l'account Google connesso sia _proprietario_ o _utente autorizzato_ su questa proprietà
- La proprietà deve avere almeno qualche giorno di storico indicizzato (Google Search Console pubblica i dati con 2-3 giorni di ritardo)

### Le previsioni sembrano poco affidabili

- Verifichi di avere almeno 60-90 giorni di storico. Al di sotto, gli indici stagionali non possono essere stimati correttamente
- Per le keyword erratiche (poco segnale, molto rumore), l'ampiezza dell'intervallo 95% è volutamente estesa — il modulo mostra esplicitamente una bassa confidenza
- Per previsioni più precise su orizzonti lunghi (60-90 giorni), aspetti di aver accumulato 6-12 mesi di storico. Il motore migliora nel tempo

### L'endpoint cron restituisce un errore 403

Il token passato in query string non corrisponde a `DFPSEO_CRON_TOKEN`. Verifichi il valore esatto in **Impostazioni → Cron**. In caso di dubbio, rigeneri il token e aggiorni la sua crontab.

### Il brief IA non viene generato

- Verifichi di aver incollato correttamente una chiave API valida per il provider attivo selezionato
- Verifichi il suo saldo sulla console del provider (Mistral, OpenAI o Anthropic)
- Se il provider restituisce un errore di rate limit, aspetti qualche minuto e riprovi
- I brief generati sono memorizzati in `dfpseo_recommendation`; in caso di errore, l'errore viene anch'esso registrato in questa tabella con lo stato `error`

## FAQ

### Il modulo funziona senza Google Search Console?

No, GSC è la fonte di dati primaria. Il modulo ha bisogno di un minimo di 60-90 giorni di storico per produrre previsioni affidabili e calcolare la stagionalità. Se il suo store è appena stato lanciato, aspetti di avere almeno 2 mesi di dati indicizzati prima di installare il modulo.

### Quanto costa un brief IA?

Dipende dal provider scelto. Con Mistral (default), conti circa 0,002 € per brief. OpenAI GPT-4o-mini circa 0,005 €. Claude Haiku circa 0,004 €. Lei fornisce la propria chiave API e paga direttamente al provider — DataFirefly non preleva alcuna commissione.

### Quante keyword può tracciare il modulo?

Non c'è un limite codificato. Una sync standard recupera fino a 250 000 righe (data × query × pagina) per chiamata — il che copre quasi la totalità degli store. Oltre, aumenti la memoria PHP allocata al worker cron.

### Il modulo è compatibile con altri moduli SEO?

Sì, Predictive SEO non scrive mai sulle pagine prodotto o sui meta — si limita a leggere GSC e produrre raccomandazioni. È totalmente compatibile con tutti i moduli SEO esistenti (DataFirefly o di terze parti).

### I miei dati GSC sono memorizzati su DataFirefly?

No. Tutti i dati rimangono sul suo server, nel suo database PrestaShop. Il modulo chiama direttamente l'API Google con le sue credenziali OAuth e chiama direttamente i provider IA con la sua chiave API. Nessun dato transita per i server DataFirefly.

### Quale orizzonte di previsione è il più affidabile?

L'orizzonte 7-14 giorni è molto affidabile (intervallo 95% stretto). L'orizzonte 30-60 giorni è indicativo (intervallo allargato). Oltre i 90 giorni, le previsioni diventano poco utili per decisioni operative — il modulo le calcola ma mostra una confidenza bassa.