# DataFirefly FAQ IA Prodotto per WooCommerce — Documentazione
> DataFirefly FAQ IA Prodotto genera automaticamente FAQ contestuali per le tue pagine prodotto WooCommerce usando OpenAI o Anthropic Claude, e inserisce i rich snippet Schema.org FAQPage nell'head per i risultati…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-08-06
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dffaqai/index.md), [en](https://www.datafirefly.com/en/documentation/dffaqai/index.md), [es](https://www.datafirefly.com/es/documentation/dffaqai/index.md), [de](https://www.datafirefly.com/de/documentation/dffaqai/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffaqai/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffaqai/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffaqai/index.md)
- Indice:
DataFirefly FAQ IA Prodotto genera automaticamente FAQ contestuali per le tue pagine prodotto WooCommerce usando OpenAI o Anthropic Claude, e inserisce i rich snippet Schema.org FAQPage nell'head per i risultati arricchiti di Google. Questa guida copre installazione, configurazione completa e uso quotidiano.
## Requisiti
- WordPress 6.0 o superiore (testato fino alla 6.6)
- WooCommerce 7.0 o superiore (testato fino alla 9.4), compatibile HPOS
- PHP da 7.4 a 8.3
- Una chiave API OpenAI ([platform.openai.com/api-keys](https://platform.openai.com/api-keys)) o Anthropic ([console.anthropic.com](https://console.anthropic.com/))
- Opzionale: Polylang o WPML per i negozi multilingua
## Installazione
1. Scarica `dffaqai-1.0.0.zip` dal tuo account DataFirefly.
2. Nell'admin di WordPress: **Plugin → Aggiungi nuovo → Carica plugin**, seleziona lo ZIP e clicca su **Installa ora**.
3. Clicca su **Attiva**. Il plugin crea la tabella di archiviazione delle FAQ e le impostazioni predefinite.
All'attivazione compare un menu **FAQ AI** nella barra laterale dell'admin con due voci: _Impostazioni_ e _Generazione in blocco_.
## Configurazione del provider IA
Vai in **FAQ AI → Impostazioni → scheda Provider**.
### Scegliere OpenAI o Anthropic Claude
- **OpenAI**: incolla la chiave API e scegli un modello — `gpt-4o-mini` (il più economico, consigliato), `gpt-4o`, `gpt-4-turbo` o `gpt-3.5-turbo`.
- **Anthropic Claude**: incolla la chiave API e scegli — `claude-haiku-4-5` (economico, consigliato), `claude-sonnet-4-6` o `claude-opus-4-7`.
Il plugin instrada automaticamente verso l'API corretta in base al provider selezionato. Puoi cambiare in qualsiasi momento: le FAQ già generate vengono conservate.
### Parametri di generazione
- **Numero di domande per prodotto**: da 1 a 15 (5 di default).
- **Temperatura**: da 0 (deterministico) a 2 (molto creativo). Default 0,7.
- **Max token**: lunghezza massima della risposta dell'IA. Default 2000.
Costo indicativo: una generazione di 5 domande costa circa 0,0005 $ con gpt-4o-mini e 0,001 $ con claude-haiku-4-5. Per 200 prodotti in 3 lingue, prevedi da 0,30 a 0,60 $ in totale.
## Scheda Prompt — personalizzare i contenuti generati
### Tono di voce
Sei stili preconfigurati: professionale, amichevole, informale, tecnico, entusiasta, rassicurante. Il tono cambia la formulazione delle risposte senza scrivere codice.
### Pubblico di destinazione
Testo libero, ad esempio «professionisti sanitari (B2B)», «primi acquirenti» o «appassionati di fai-da-te». L'IA adatta vocabolario, riferimenti e profondità.
### Prompt di sistema personalizzato
Lascia vuoto per usare il prompt predefinito costruito da tono e pubblico. Se compilato, sostituisce completamente le istruzioni predefinite — utile per i negozi con una linea editoriale rigorosa.
### Direttive aggiuntive
Istruzioni aggiunte a ogni prompt, ad esempio «menzionare sempre la garanzia di 2 anni», «evitare i superlativi», «non confrontare con i concorrenti».
### Contesto prodotto da includere
Tre caselle arricchiscono il contesto inviato all'IA: **categoria principale**, **marchio** (le tassonomie `product_brand`, `pwb-brand` e `yith_product_brand` vengono rilevate automaticamente) e **attributi WooCommerce**. Sui prodotti tecnici, includere gli attributi migliora molto la pertinenza delle domande.
## Scheda Visualizzazione e SEO
### Posizione di visualizzazione
Cinque hook WooCommerce tra cui scegliere:
- `woocommerce_after_single_product_summary` — sotto le schede (default)
- `woocommerce_single_product_summary` — all'interno del riepilogo prodotto
- `woocommerce_product_meta_end` — alla fine dei meta prodotto
- `woocommerce_after_single_product` — dopo tutta l'area prodotto
- `woocommerce_before_single_product` — prima di tutta l'area prodotto
La **priorità dell'hook** (default 15) è configurabile per convivere con altri plugin.
### Modalità di visualizzazione
Fisarmonica (prima domanda aperta, navigazione da tastiera ARIA) o tutte le risposte espanse.
### Rich snippet FAQPage
Con l'opzione attiva, il plugin inserisce il JSON-LD Schema.org FAQPage nell'head di ogni pagina prodotto con almeno una FAQ attiva. La codifica usa `JSON_HEX_TAG`, `JSON_HEX_AMP`, `JSON_HEX_APOS` e `JSON_HEX_QUOT` e supera il Rich Results Test di Google.
### Titolo della FAQ per lingua
Un campo titolo per ogni lingua attiva del sito, con valori predefiniti inclusi per FR, EN, ES, DE, IT, PT e NL.
### Categorie escluse
Elenco di ID di categorie WooCommerce separati da virgola. I prodotti di queste categorie vengono ignorati nella generazione in blocco e automatica (prodotti virtuali, gift card, ecc.).
## La metabox FAQ nella scheda prodotto
Nella schermata di modifica di ogni prodotto, la metabox **FAQ AI** offre pieno controllo:
- **Genera con IA**: crea un set di domande/risposte per la lingua selezionata.
- **Aggiungi una domanda** manuale in qualsiasi momento.
- **Modifica** una domanda o una risposta: la riga si salva automaticamente alla perdita del focus.
- **Riordina** con drag-and-drop tramite la maniglia a sinistra di ogni riga.
- **Attiva/disattiva** una voce senza eliminarla.
- **Elimina** definitivamente una voce.
Un selettore di lingua in cima alla metabox passa istantaneamente tra le traduzioni Polylang o WPML del prodotto — ogni traduzione ha il proprio set di FAQ.
## Generazione in blocco
Menu **FAQ AI → Generazione in blocco**:
1. Scegli la **lingua di destinazione**: lingua predefinita, una lingua specifica o tutte le lingue attive.
2. Spunta facoltativamente **Forza rigenerazione** per sovrascrivere le FAQ esistenti (utile dopo aver cambiato tono o provider).
3. Clicca su **Avvia**.
L'elaborazione è sequenziale (circa un prodotto al secondo a seconda della latenza dell'API) con barra di avanzamento in tempo reale, contatore dei prodotti elaborati e registro errori per prodotto. Il pulsante **Stop** interrompe in modo pulito tra due prodotti. Vengono elaborati solo i prodotti pubblicati; le categorie escluse vengono ignorate.
Tieni aperta la scheda del browser durante la generazione in blocco: l'elaborazione è pilotata dal browser per consentire la barra di avanzamento e lo stop su richiesta.
## Generazione automatica alla creazione del prodotto
Opzione della scheda Provider: quando è attiva, il plugin genera automaticamente una FAQ nella lingua predefinita ogni volta che viene salvato un prodotto che non ne ha. Le FAQ esistenti non vengono mai sovrascritte da questo meccanismo.
## Multilingua con Polylang e WPML
Il plugin rileva automaticamente Polylang (`pll_languages_list`, `pll_get_post_translations`) e WPML (`wpml_active_languages`, `wpml_object_id`). Ogni traduzione di un prodotto riceve il proprio set di FAQ, generato nativamente nella lingua di destinazione — non una traduzione dell'originale. La modalità in blocco «tutte le lingue» scorre ogni traduzione di ogni prodotto.
## Verificare i rich snippet
1. Apri una pagina prodotto con almeno una FAQ attiva.
2. Visualizza il sorgente della pagina e cerca `application/ld+json`: deve essere presente un blocco `"@type":"FAQPage"`.
3. Testa l'URL nel [Rich Results Test di Google](https://search.google.com/test/rich-results): il rilevamento «FAQ» deve risultare valido.
Google decide da solo se mostrare i rich result nella SERP; un markup valido è condizione necessaria ma non sufficiente. La visualizzazione compare di solito dopo la reindicizzazione della pagina.
## Risoluzione dei problemi
### «La chiave API del provider IA non è configurata»
Inserisci la chiave del provider attivo nella scheda Provider. Verifica che non ci siano spazi prima o dopo la chiave.
### Errore API durante la generazione
Vai in **WooCommerce → Stato → Log** e seleziona la sorgente `dffaqai`: ogni errore API viene registrato con il codice HTTP e il messaggio del provider (chiave non valida, quota superata, modello sconosciuto…).
### Il blocco FAQ non viene visualizzato
Verifica che il prodotto abbia almeno una FAQ _attiva_ nella lingua visualizzata e che il tema esegua l'hook scelto. In caso di dubbio, torna all'hook predefinito `woocommerce_after_single_product_summary`, presente in tutti i temi WooCommerce standard.
### Le domande generate sono nella lingua sbagliata
La lingua di generazione segue la traduzione del prodotto (Polylang/WPML) o il locale del sito in modalità monolingua. Verifica il selettore di lingua della metabox prima di generare.
## Disinstallazione
La disattivazione conserva tutti i dati. L'**eliminazione** del plugin esegue `uninstall.php`: la tabella SQL delle FAQ e tutte le opzioni `dffaqai_*` vengono rimosse definitivamente.
## Supporto
Il supporto avviene via email con risposta entro 24 ore lavorative (FR/EN). Se possibile, allega il log `dffaqai` e le versioni di WordPress/WooCommerce/PHP.