# 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…

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

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

**Nota** — Non è richiesto alcun `composer install`. Il modulo integra un autoloader PSR-4 minimale sotto il namespace DataFirefly Dfaipaa.

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

**Suggerimento** — La modalità di inserimento manuale consente di usare il modulo senza alcun abbonamento di scraping: inserisci tu le domande e l'IA si occupa delle risposte.

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

**Importante** — Se il tuo strumento di decompressione salta le cartelle `vendor/`, l'autoloader risulterà mancante e il modulo genererà un errore «Class not found». Decomprimi con `unzip` o carica lo ZIP direttamente dal back-office, che gestisce correttamente l'albero dei file.

## Configurazione — Scraping

Scheda **AI People Also Ask › Configurazione**, prima sezione.

| Campo | Descrizione | Predefinito |
| --- | --- | --- |
| Provider | `serpapi`, `dataforseo` o `manual` | `serpapi` |
| Chiave API | Chiave SerpApi o credenziali DataForSEO nel formato `login:password` | vuoto |
| Lingua | Codice ISO a 2 lettere usato nella query a Google | `fr` |
| Paese | Codice ISO a 2 lettere del mercato di destinazione | `FR` |
| Max domande per parola chiave | Limite per operazione di scraping | `8` |
| Intervallo di aggiornamento | In giorni, oltre i quali una parola chiave è considerata scaduta | `30` |

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

| Campo | Descrizione | Predefinito |
| --- | --- | --- |
| Provider | `mistral`, `openai` o `anthropic` | `mistral` |
| Modello | Identificativo del modello presso il provider | `mistral-large-latest` |
| Chiave API | Chiave del provider selezionato | vuoto |
| Temperatura | Da 0.0 a 1.0 — più basso = più fattuale | `0.3` |
| Token max | Lunghezza massima della risposta generata | `500` |
| Tono | Testo libero: esperto, didattico, commerciale, cordiale… | vuoto |
| Voce del brand | Istruzioni aggiuntive per allineare lo stile editoriale | vuoto |
| Pubblicazione automatica | Pubblica automaticamente ogni risposta generata | disattivato |

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

**Suggerimento** — Se un modello più piccolo restituisce comunque markdown, abbassa la temperatura a 0.2 e aggiungi «solo HTML, niente markdown» nel campo Voce del brand.

## Configurazione — Visualizzazione

Terza sezione della scheda Configurazione.

| Campo | Descrizione | Predefinito |
| --- | --- | --- |
| Modalità prodotto | `tab` (scheda) o `footer` (blocco a fondo pagina) | `tab` |
| Attiva sui prodotti | Mostra la FAQ sulle schede prodotto | attivo |
| Attiva sulle categorie | Mostra la FAQ a fondo pagina categoria | attivo |
| Titolo scheda | Etichetta localizzata della scheda prodotto | «Domande frequenti» |
| Titolo prodotto | Titolo del blocco in modalità footer | localizzato |
| Titolo categoria | Titolo del blocco categoria | localizzato |
| Emetti JSON-LD | Inietta il markup FAQPage | attivo |

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

| Stato | Significato | Visibile nel negozio |
| --- | --- | --- |
| `pending` | Domanda catturata, ancora senza risposta IA | No |
| `generated` | Risposta generata, in attesa di convalida | No |
| `published` | Convalidata e pubblicata | Sì |
| `rejected` | Scartata manualmente | No |

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

**Suggerimento** — Valida il tuo markup con lo strumento di test dei risultati avanzati di Google. Nota che Google ha limitato la visualizzazione dei rich snippet FAQ ai siti governativi e sanitari, ma il markup resta prezioso per i motori generativi (ChatGPT, Perplexity, Gemini) che lo sfruttano attivamente.

## 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
```

**Importante** — Dimensiona il parametro `--limit` in base alle tue quote API. Un lotto di 30 parole chiave consuma 30 richieste SerpApi; con il piano gratuito (100 al mese), un'esecuzione settimanale è più adatta di una quotidiana.

## 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 **contact@datafirefly.com** o consulta la tua area cliente su [datafirefly.com](https://www.datafirefly.com/it/).