DataFirefly Produkt-FAQ KI für WooCommerce — Dokumentation

DataFirefly Produkt-FAQ KI erzeugt automatisch kontextbezogene FAQs für Ihre WooCommerce-Produktseiten mit OpenAI oder Anthropic Claude und fügt Schema.org-FAQPage-Rich-Snippets in den head ein — für Google Rich Results. Diese Anleitung behandelt Installation, vollständige Konfiguration und den täglichen Einsatz.

Voraussetzungen

• WordPress 6.0 oder höher (getestet bis 6.6)
• WooCommerce 7.0 oder höher (getestet bis 9.4), HPOS-kompatibel
• PHP 7.4 bis 8.3
• Ein OpenAI-API-Schlüssel (platform.openai.com/api-keys) oder ein Anthropic-Schlüssel (console.anthropic.com)
• Optional: Polylang oder WPML für mehrsprachige Shops

Installation

1. Laden Sie dffaqai-1.0.0.zip aus Ihrem DataFirefly-Konto herunter.
2. Im WordPress-Admin: Plugins → Installieren → Plugin hochladen, ZIP auswählen und auf Jetzt installieren klicken.
3. Klicken Sie auf Aktivieren. Das Plugin legt seine FAQ-Speichertabelle und die Standardeinstellungen an.

KI-Anbieter konfigurieren

Gehen Sie zu FAQ AI → Einstellungen → Tab Anbieter.

OpenAI oder Anthropic Claude wählen

• OpenAI: API-Schlüssel einfügen und ein Modell wählen — gpt-4o-mini (am günstigsten, empfohlen), gpt-4o, gpt-4-turbo oder gpt-3.5-turbo.
• Anthropic Claude: API-Schlüssel einfügen und wählen — claude-haiku-4-5 (günstig, empfohlen), claude-sonnet-4-6 oder claude-opus-4-7.

Das Plugin leitet automatisch an die richtige API weiter. Sie können jederzeit wechseln: bereits erzeugte FAQs bleiben erhalten.

Erzeugungsparameter

• Anzahl Fragen je Produkt: 1 bis 15 (Standard 5).
• Temperatur: 0 (deterministisch) bis 2 (sehr kreativ). Standard 0,7.
• Max. Tokens: maximale Länge der KI-Antwort. Standard 2000.

Tab Prompt — die erzeugten Inhalte anpassen

Tonalität

Sechs vorkonfigurierte Stile: professionell, freundlich, locker, technisch, begeistert, beruhigend. Die Tonalität verändert die Formulierung der Antworten ohne Code.

Zielgruppe

Freitext, z. B. „medizinische Fachkräfte (B2B)“, „Erstkäufer“ oder „Heimwerker“. Die KI passt Wortschatz, Bezüge und Tiefe an.

Eigener System-Prompt

Leer lassen, um den Standard-Prompt aus Tonalität und Zielgruppe zu verwenden. Wenn ausgefüllt, ersetzt er die Standardanweisungen vollständig — nützlich für Shops mit strikten Redaktionsrichtlinien.

Zusätzliche Vorgaben

Anweisungen, die an jeden Prompt angehängt werden, z. B. „immer die 2-Jahres-Garantie erwähnen“, „keine Superlative“, „keine Vergleiche mit Wettbewerbern“.

Einzubeziehender Produktkontext

Drei Checkboxen reichern den an die KI gesendeten Kontext an: primäre Kategorie, Marke (die Taxonomien product_brand, pwb-brand und yith_product_brand werden automatisch erkannt) und WooCommerce-Attribute. Bei technischen Produkten verbessert die Einbindung der Attribute die Relevanz der Fragen deutlich.

Tab Anzeige & SEO

Anzeigeposition

Fünf WooCommerce-Hooks zur Auswahl:

• woocommerce_after_single_product_summary — unter den Tabs (Standard)
• woocommerce_single_product_summary — innerhalb der Produktzusammenfassung
• woocommerce_product_meta_end — am Ende der Produkt-Meta
• woocommerce_after_single_product — nach dem gesamten Produktbereich
• woocommerce_before_single_product — vor dem gesamten Produktbereich

Die Hook-Priorität (Standard 15) ist konfigurierbar, um mit anderen Plugins zu koexistieren.

Anzeigemodus

Akkordeon (erste Frage offen, ARIA-Tastaturnavigation) oder alle Antworten ausgeklappt.

FAQPage-Rich-Snippets

Bei aktivierter Option fügt das Plugin das Schema.org-FAQPage-JSON-LD in den head jeder Produktseite mit mindestens einer aktiven FAQ ein. Die Codierung nutzt JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS und JSON_HEX_QUOT und besteht den Rich-Results-Test von Google.

FAQ-Titel je Sprache

Ein Titelfeld je aktiver Website-Sprache, mit Voreinstellungen für FR, EN, ES, DE, IT, PT und NL.

Ausgeschlossene Kategorien

Kommagetrennte Liste von WooCommerce-Kategorie-IDs. Produkte dieser Kategorien werden bei der Massen- und Auto-Erzeugung übersprungen (virtuelle Produkte, Geschenkkarten usw.).

Die FAQ-Metabox auf der Produktseite

Auf jedem Produktbearbeitungsbildschirm bietet die Metabox FAQ AI volle Kontrolle:

• Mit KI erzeugen: erstellt einen Q&A-Satz für die gewählte Sprache.
• Frage hinzufügen — jederzeit manuell.
• Bearbeiten einer Frage oder Antwort: die Zeile speichert sich automatisch beim Verlassen des Felds.
• Neu ordnen per Drag-and-Drop über den Griff links an jeder Zeile.
• Aktivieren/deaktivieren eines Eintrags ohne Löschen.
• Löschen eines Eintrags endgültig.

Ein Sprachumschalter oben in der Metabox wechselt sofort zwischen den Polylang- oder WPML-Übersetzungen des Produkts — jede Übersetzung hat einen eigenen FAQ-Satz.

Massenerzeugung

Menü FAQ AI → Massenerzeugung:

1. Wählen Sie die Zielsprache: Standardsprache, eine bestimmte Sprache oder alle aktiven Sprachen.
2. Aktivieren Sie optional Neuerzeugung erzwingen, um bestehende FAQs zu überschreiben (nützlich nach einer Änderung von Tonalität oder Anbieter).
3. Klicken Sie auf Starten.

Die Verarbeitung erfolgt sequenziell (etwa ein Produkt pro Sekunde, abhängig von der API-Latenz) mit Echtzeit-Fortschrittsbalken, Zähler der verarbeiteten Produkte und Fehlerprotokoll je Produkt. Die Schaltfläche Stopp bricht sauber zwischen zwei Produkten ab. Es werden nur veröffentlichte Produkte verarbeitet; ausgeschlossene Kategorien werden übersprungen.

Auto-Erzeugung bei Produktanlage

Option im Tab Anbieter: Wenn aktiviert, erzeugt das Plugin automatisch eine FAQ in der Standardsprache, sobald ein Produkt ohne FAQ gespeichert wird. Bestehende FAQs werden durch diesen Mechanismus nie überschrieben.

Mehrsprachig mit Polylang & WPML

Das Plugin erkennt Polylang (pll_languages_list, pll_get_post_translations) und WPML (wpml_active_languages, wpml_object_id) automatisch. Jede Übersetzung eines Produkts erhält einen eigenen FAQ-Satz, der nativ in der Zielsprache erzeugt wird — keine Übersetzung des Originals. Der Massenmodus „alle Sprachen“ durchläuft jede Übersetzung jedes Produkts.

Rich Snippets überprüfen

1. Öffnen Sie eine Produktseite mit mindestens einer aktiven FAQ.
2. Zeigen Sie den Quelltext an und suchen Sie nach application/ld+json: Ein Block "@type":"FAQPage" muss vorhanden sein.
3. Testen Sie die URL im Rich-Results-Test von Google: Die Erkennung „FAQ“ muss gültig sein.

Fehlerbehebung

„Der API-Schlüssel des KI-Anbieters ist nicht konfiguriert“

Tragen Sie den Schlüssel des aktiven Anbieters im Tab Anbieter ein. Achten Sie darauf, dass keine Leerzeichen vor oder nach dem Schlüssel stehen.

API-Fehler während der Erzeugung

Gehen Sie zu WooCommerce → Status → Protokolle und wählen Sie die Quelle dffaqai: Jeder API-Fehler wird dort mit HTTP-Code und Anbieter-Meldung protokolliert (ungültiger Schlüssel, Kontingent überschritten, unbekanntes Modell …).

Der FAQ-Block wird nicht angezeigt

Prüfen Sie, ob das Produkt mindestens eine aktive FAQ in der angezeigten Sprache hat und ob Ihr Theme den gewählten Hook ausführt. Im Zweifel kehren Sie zum Standard-Hook woocommerce_after_single_product_summary zurück, der in allen Standard-WooCommerce-Themes vorhanden ist.

Erzeugte Fragen sind in der falschen Sprache

Die Erzeugungssprache folgt der Produktübersetzung (Polylang/WPML) bzw. der Website-Locale bei einsprachigen Sites. Prüfen Sie den Sprachumschalter der Metabox vor der Erzeugung.

Deinstallation

Die Deaktivierung erhält alle Daten. Beim Löschen des Plugins wird uninstall.php ausgeführt: Die FAQ-SQL-Tabelle und alle dffaqai_*-Optionen werden endgültig entfernt.

Support

Der Support erfolgt per E-Mail mit Antwort innerhalb von 24 Arbeitsstunden (FR/EN). Fügen Sie nach Möglichkeit das dffaqai-Protokoll sowie Ihre WordPress-/WooCommerce-/PHP-Versionen bei.