AI People Also Ask — Documentazione completa (dfaipaa)

Panoramica

AI People Also Ask (slug tecnico: dfaipaa) cattura le domande che i tuoi clienti pongono realmente a Google — i blocchi «People Also Ask» — genera le risposte con l’IA che preferisci e pubblica una FAQ marcata schema.org sulle tue schede prodotto e pagine categoria.

Il modulo industrializza una pipeline completa in quattro fasi:

• Scraping — cattura delle domande PAA sulle tue parole chiave tramite SerpApi, DataForSEO o inserimento manuale.
• Generazione IA — redazione delle risposte con Mistral, OpenAI o Anthropic, con tono e voce del brand configurabili.
• Flusso editoriale — revisione, assegnazione a prodotti e categorie, pubblicazione (manuale o automatica).
• Pubblicazione — fisarmonica FAQ accessibile nel negozio più JSON-LD FAQPage per Google e i motori generativi.

Requisiti

• PrestaShop 8.0.0 → 9.99.99
• PHP 8.1, 8.2 o 8.3
• MySQL 5.7 / MariaDB 10.4 o superiore
• Una chiave API per almeno un provider IA (Mistral, OpenAI o Anthropic)
• Opzionale: una chiave SerpApi o un account DataForSEO per automatizzare lo scraping
• Connessioni HTTPS in uscita (cURL) consentite dal tuo hosting

Installazione

1. Scarica lo ZIP dfaipaa.zip dal tuo account DataFirefly.
2. Nel back-office PrestaShop, vai su Moduli › Gestore moduli › Carica un modulo.
3. Trascina lo ZIP, attendi la conferma e clicca su Installa.
4. Compare un nuovo menu AI People Also Ask nella colonna di sinistra, con tre schede: Configurazione, Parole chiave, Domande.

L’installazione crea 4 tabelle (prefisso ps_dfaipaa_), imposta i valori di configurazione predefiniti e installa 4 schede di amministrazione (una padre più tre figlie) con etichette localizzate in FR, EN, ES, DE, IT e NL.

Configurazione — Scraping

Scheda AI People Also Ask › Configurazione, prima sezione.

Ottenere una chiave SerpApi

Crea un account su serpapi.com. Il piano gratuito offre 100 richieste al mese, ovvero circa 100 parole chiave analizzate. La chiave si trova nella dashboard, sezione «Your Account». Il modulo interroga l’endpoint di ricerca Google e utilizza il blocco related_questions della risposta.

Ottenere un account DataForSEO

Crea un account su dataforseo.com. Ricevi una coppia utente / password da incollare nel campo Chiave API nel formato login:password (il modulo gestisce l’autenticazione HTTP Basic). DataForSEO fattura a consumo, più adatto ai volumi elevati. Il modulo usa l’endpoint SERP Google organic live advanced ed estrae gli elementi people_also_ask.

La mappatura dei codici di localizzazione è integrata per questi mercati: FR, BE, CH, LU, CA, US, UK, IE, ES, PT, IT, DE, AT, NL, PL, BR e MX.

Modalità inserimento manuale

Seleziona manual per disattivare qualsiasi chiamata esterna. Aggiungi tu stesso le domande dalla scheda Domande; la generazione IA resta pienamente operativa.

Configurazione — Intelligenza artificiale

Seconda sezione della scheda Configurazione.

Modelli consigliati

• Mistral — mistral-large-latest per la qualità, mistral-small-latest per ridurre i costi sui grandi volumi.
• OpenAI — gpt-4o-mini offre un ottimo rapporto qualità-prezzo; gpt-4o per cataloghi tecnici esigenti.
• Anthropic — claude-sonnet-4-6 per risposte sfumate e ben strutturate.

Vincoli imposti al modello

Il modulo costruisce un prompt di sistema rigoroso, indipendente dal provider: risposte da 60 a 120 parole, solo HTML semplice (paragrafi, grassetto, corsivo, elenchi), niente markdown, niente tag di intestazione, niente script. Il contesto dell’entità (nome e descrizione del prodotto o della categoria, troncati a 1200 caratteri) e la parola chiave di origine vengono iniettati per ancorare la risposta. Lo snippet Google originale è fornito come riferimento con l’istruzione esplicita di riformulare — mai di copiare.

Configurazione — Visualizzazione

Terza sezione della scheda Configurazione.

In modalità tab, il modulo si appoggia al meccanismo nativo ProductExtraContent di PrestaShop: la FAQ appare come scheda accanto a «Descrizione» e «Dettagli prodotto», senza sovrascrivere template.

Flusso editoriale

Fase 1 — Aggiungere parole chiave

Scheda Parole chiave. Incolla il tuo elenco nell’area di testo, una parola chiave per riga, poi conferma. I duplicati vengono ignorati automaticamente (l’aggiunta è idempotente per parola chiave, lingua e negozio).

Scegli parole chiave allineate all’intento d’acquisto: «macchina da caffè automatica», «miglior caffè in grani», «manutenzione macchina caffè». Evita le query puramente di marca, che raramente attivano blocchi PAA.

Fase 2 — Scraping

Due opzioni:

• Scraping — pulsante individuale su ogni riga, utile per testare la configurazione.
• Scraping di tutte le scadute — elabora a lotti di 20 le parole chiave la cui ultima cattura supera l’intervallo di aggiornamento.

Ogni domanda catturata viene salvata con un hash di unicità (domanda + lingua + negozio): rieseguire lo scraping non crea mai duplicati, aggiorna soltanto la data dell’ultima cattura.

Fase 3 — Generare le risposte

Scheda Domande. Filtra per stato pending, seleziona le domande con le caselle e avvia l’azione di massa Genera. È disponibile anche un pulsante individuale su ogni riga.

Il contesto dell’entità viene costruito a partire dalla prima assegnazione della domanda. Per risposte migliori, assegna la domanda a un prodotto o a una categoria prima di generare: l’IA disporrà così del nome e della descrizione dell’entità.

Fase 4 — Revisionare e assegnare

Clicca su una domanda per aprire il modulo di modifica. Puoi:

• correggere la risposta HTML nell’editor avanzato;
• assegnare la domanda a uno o più prodotti e categorie (relazione N a N);
• riordinare le assegnazioni per controllare l’ordine della fisarmonica;
• rifiutare una domanda fuori tema (stato rejected, conservata nel database ma mai visualizzata).

Fase 5 — Pubblicare

Passa lo stato a published. La FAQ appare immediatamente nel negozio, accompagnata dal suo JSON-LD.

Se l’opzione Pubblicazione automatica è attiva, le fasi 4 e 5 si fondono: la generazione pubblica direttamente. Pratico per una pipeline completamente automatizzata, consigliabile solo per cataloghi in cui la revisione umana non è critica.

Stati delle domande

Visualizzazione nel negozio

La fisarmonica si basa sugli elementi HTML nativi details e summary, il che garantisce:

• navigazione da tastiera funzionante senza JavaScript;
• contenuto indicizzabile dai motori anche da chiuso;
• compatibilità con tutti i browser moderni.

Il primo elemento è aperto per impostazione predefinita. Viene caricato un CSS leggero, interamente sovrascrivibile dal tuo tema figlio. Tutte le classi usano il prefisso dfaipaa-faq per evitare collisioni.

Eventi JavaScript

Lo script frontend emette due eventi personalizzati che puoi collegare al tuo strumento di analytics:

document.addEventListener('dfaipaa:open', function (e) {
  // e.detail.question, e.detail.index, e.detail.type, e.detail.entityId
  gtag('event', 'faq_open', { question: e.detail.question });
});

document.addEventListener('dfaipaa:close', function (e) {
  console.log('FAQ chiusa:', e.detail.question);
});

Il file views/js/front.js contiene inoltre una costante SINGLE_OPEN (a false per impostazione predefinita): impostala a true per consentire un solo pannello aperto alla volta.

Deep-linking

Un’ancora della forma #dfaipaa-q-123 apre automaticamente la domanda corrispondente e fa scorrere la pagina fino ad essa. Utile per condividere una risposta specifica da un’email o da un ticket di assistenza.

Markup JSON-LD FAQPage

A ogni caricamento di pagina prodotto o categoria con almeno una domanda pubblicata, il modulo inietta un blocco JSON-LD subito prima della chiusura del corpo del documento (hook displayBeforeBodyClosingTag).

Struttura emessa: un nodo FAQPage, un array mainEntity e, per ogni voce, un nodo Question contenente un acceptedAnswer di tipo Answer. Il contenuto HTML delle risposte viene ripulito prima dell’emissione: i tag di script e stile e gli attributi di evento vengono rimossi.

Automazione tramite cron

È fornito uno script CLI per eseguire la pipeline senza intervento manuale.

# Scraping delle parole chiave scadute (max 20 per impostazione predefinita)
php modules/dfaipaa/cli/cron.php scrape --limit=20

# Generare le risposte IA per le domande in attesa
php modules/dfaipaa/cli/cron.php generate --limit=10

# Concatenare scraping e generazione
php modules/dfaipaa/cli/cron.php all --limit=20

Esempio di crontab, esecuzione notturna alle 3:

0 3 * * * cd /var/www/prestashop && php modules/dfaipaa/cli/cron.php all --limit=30 >> /var/log/dfaipaa.log 2>&1

Multilingua e multinegozio

Le domande sono indicizzate per id_lang e id_shop. In pratica:

• la stessa parola chiave analizzata in italiano e in inglese produce due insiemi distinti di domande;
• le risposte sono generate nella lingua della domanda, applicando il prompt una direttiva linguistica esplicita (fr, en, es, de, it, nl, pt, pl);
• in multinegozio, le domande e le assegnazioni di un negozio non appaiono mai in un altro;
• i titoli di visualizzazione (scheda, prodotto, categoria) sono salvati come configurazione localizzata.

Risoluzione dei problemi

Lo scraping non restituisce alcuna domanda

• Verifica la tua quota presso il provider: SerpApi si interrompe silenziosamente oltre il piano gratuito.
• Controlla la coerenza lingua / paese: «it» con «US» dà risultati incoerenti.
• Alcune parole chiave semplicemente non attivano blocchi PAA su Google. Prova la query manualmente in una finestra anonima.
• Per DataForSEO, verifica il formato login:password del campo Chiave API.

L’IA restituisce markdown invece di HTML

Abbassa la temperatura a 0.2 o passa a un modello più capace. Il prompt impone già regole HTML rigorose, ma i modelli più leggeri possono ignorarle in parte.

La FAQ non appare nel negozio

• Verifica che almeno una domanda sia in stato published.
• Verifica che sia assegnata all’entità consultata (prodotto o categoria).
• Controlla che la visualizzazione sia attiva per quel tipo di entità nella configurazione.
• Svuota la cache Smarty da Parametri avanzati › Prestazioni.

Il JSON-LD non appare nel codice sorgente

Assicurati che l’opzione «Emetti JSON-LD» sia attiva e che il tuo tema chiami effettivamente l’hook displayBeforeBodyClosingTag. Alcuni temi di terze parti lo omettono: in tal caso aggiungi {hook h='displayBeforeBodyClosingTag'} prima della chiusura del corpo nel tuo layouts/layout-both-columns.tpl.

Errore «Class not found» dopo l’installazione

La cartella vendor/ non è stata estratta. Reinstalla il modulo caricando lo ZIP dal back-office anziché decomprimerlo manualmente.

Consultare i log delle operazioni

Tutte le operazioni (scraping, generazione, pubblicazione) vengono registrate. Per indagare:

SELECT * FROM ps_dfaipaa_log ORDER BY date_add DESC LIMIT 50;

Disinstallazione

Da Moduli › Gestore moduli, clicca su Disinstalla. L’operazione elimina le 4 tabelle ps_dfaipaa_*, le 4 schede di amministrazione e tutte le chiavi di configurazione DFAIPAA_. Il contenuto generato viene perso definitivamente: esporta le tue domande in anticipo se desideri conservarle.

Riferimento tecnico

• Slug tecnico: dfaipaa
• Namespace: DataFirefly Dfaipaa (PSR-4, autoloader integrato)
• Tabelle create: ps_dfaipaa_keyword, ps_dfaipaa_question, ps_dfaipaa_assignment, ps_dfaipaa_log
• Hook utilizzati: displayHeader, displayProductExtraContent, displayFooterProduct, displayCategoryFooter, displayBeforeBodyClosingTag, actionFrontControllerSetMedia, actionAdminControllerSetMedia, actionProductUpdate, actionProductSave, actionCategoryUpdate, actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter
• Schede back-office: AdminDfaipaa (padre), AdminDfaipaaConfig, AdminDfaipaaKeywords, AdminDfaipaaQuestions
• Chiavi di configurazione: DFAIPAA_SCRAPER_PROVIDER, DFAIPAA_SCRAPER_API_KEY, DFAIPAA_SCRAPER_LANG, DFAIPAA_SCRAPER_COUNTRY, DFAIPAA_SCRAPER_MAX_PER_KEYWORD, DFAIPAA_AI_PROVIDER, DFAIPAA_AI_MODEL, DFAIPAA_AI_API_KEY, DFAIPAA_AI_TEMPERATURE, DFAIPAA_AI_MAX_TOKENS, DFAIPAA_AI_TONE, DFAIPAA_AI_BRAND_VOICE, DFAIPAA_AUTO_PUBLISH, DFAIPAA_REFRESH_INTERVAL, DFAIPAA_PRODUCT_MODE, DFAIPAA_EMIT_JSONLD, DFAIPAA_TAB_TITLE, DFAIPAA_PRODUCT_TITLE, DFAIPAA_CATEGORY_TITLE
• CLI: modules/dfaipaa/cli/cron.php (comandi scrape, generate, all)
• Template frontend: views/templates/hook/faq.tpl

Conformità GDPR

Il modulo non raccoglie né memorizza alcun dato personale: vengono registrati solo parole chiave, domande, risposte generate e log tecnici delle operazioni. Nel negozio non viene depositato alcun cookie. Le chiamate alle API esterne (scraping, IA) trasmettono solo la parola chiave, la domanda e il contesto del prodotto — mai dati dei clienti.

Assistenza

Per qualsiasi domanda tecnica, contatta il team DataFirefly all’indirizzo [email protected] o consulta la tua area cliente su datafirefly.com.