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 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) o Anthropic (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.

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.

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.

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: il rilevamento «FAQ» deve risultare valido.

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.