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 arrivo. Per ogni opportunità rilevata, può generare in un clic un brief di contenuto strutturato via Mistral, OpenAI o Claude.

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.

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 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).

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 → 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 → 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 → 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

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.