DataFirefly FAQ AI dla produktów WooCommerce — Dokumentacja

DataFirefly FAQ AI automatycznie generuje kontekstowe sekcje FAQ dla stron produktów WooCommerce przy użyciu OpenAI lub Anthropic Claude oraz wstrzykuje rich snippets Schema.org FAQPage do sekcji head — dla wyników rozszerzonych Google. Ten przewodnik obejmuje instalację, pełną konfigurację i codzienne użytkowanie.

Wymagania

• WordPress 6.0 lub nowszy (testowany do 6.6)
• WooCommerce 7.0 lub nowszy (testowany do 9.4), zgodny z HPOS
• PHP od 7.4 do 8.3
• Klucz API OpenAI (platform.openai.com/api-keys) lub Anthropic (console.anthropic.com)
• Opcjonalnie: Polylang lub WPML dla sklepów wielojęzycznych

Instalacja

1. Pobierz plik dffaqai-1.0.0.zip ze swojego konta DataFirefly.
2. W panelu WordPress: Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer, wybierz plik ZIP i kliknij Zainstaluj teraz.
3. Kliknij Włącz. Wtyczka utworzy tabelę przechowywania FAQ oraz ustawienia domyślne.

Konfiguracja dostawcy AI

Przejdź do FAQ AI → Ustawienia → zakładka Dostawca.

Wybór OpenAI lub Anthropic Claude

• OpenAI: wklej klucz API i wybierz model — gpt-4o-mini (najtańszy, zalecany), gpt-4o, gpt-4-turbo lub gpt-3.5-turbo.
• Anthropic Claude: wklej klucz API i wybierz — claude-haiku-4-5 (ekonomiczny, zalecany), claude-sonnet-4-6 lub claude-opus-4-7.

Wtyczka automatycznie kieruje żądania do właściwego API na podstawie wybranego dostawcy. Możesz przełączać się w dowolnym momencie — już wygenerowane FAQ zostają zachowane.

Parametry generowania

• Liczba pytań na produkt: od 1 do 15 (domyślnie 5).
• Temperatura: od 0 (deterministycznie) do 2 (bardzo kreatywnie). Domyślnie 0,7.
• Max tokens: maksymalna długość odpowiedzi AI. Domyślnie 2000.

Zakładka Prompt — personalizacja generowanych treści

Ton wypowiedzi

Sześć gotowych stylów: profesjonalny, przyjazny, swobodny, techniczny, entuzjastyczny, uspokajający. Ton zmienia sposób formułowania odpowiedzi bez pisania kodu.

Grupa docelowa

Dowolny tekst, np. „profesjonaliści medyczni (B2B)”, „kupujący po raz pierwszy” lub „majsterkowicze”. AI dostosowuje słownictwo, odniesienia i poziom szczegółowości.

Własny prompt systemowy

Pozostaw puste, aby użyć domyślnego promptu zbudowanego z tonu i grupy docelowej. Jeśli go wypełnisz, całkowicie zastąpi instrukcje domyślne — przydatne dla sklepów z rygorystyczną linią redakcyjną.

Dodatkowe wytyczne

Instrukcje dołączane do każdego promptu, np. „zawsze wspominaj o 2-letniej gwarancji”, „unikaj superlatywów”, „nie porównuj z konkurencją”.

Kontekst produktu do uwzględnienia

Trzy pola wyboru wzbogacają kontekst wysyłany do AI: kategoria główna, marka (taksonomie product_brand, pwb-brand i yith_product_brand wykrywane automatycznie) oraz atrybuty WooCommerce. W przypadku produktów technicznych uwzględnienie atrybutów znacznie poprawia trafność pytań.

Zakładka Wyświetlanie i SEO

Pozycja wyświetlania

Pięć hooków WooCommerce do wyboru:

• woocommerce_after_single_product_summary — pod zakładkami (domyślnie)
• woocommerce_single_product_summary — wewnątrz podsumowania produktu
• woocommerce_product_meta_end — na końcu meta produktu
• woocommerce_after_single_product — po całym obszarze produktu
• woocommerce_before_single_product — przed całym obszarem produktu

Priorytet hooka (domyślnie 15) można konfigurować, aby współistnieć z innymi wtyczkami.

Tryb wyświetlania

Akordeon (pierwsze pytanie otwarte, nawigacja klawiaturą zgodna z ARIA) lub wszystkie odpowiedzi rozwinięte.

Rich snippets FAQPage

Gdy opcja jest włączona, wtyczka wstrzykuje JSON-LD Schema.org FAQPage do sekcji head każdej strony produktu z co najmniej jednym aktywnym FAQ. Kodowanie używa flag JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS i JSON_HEX_QUOT i przechodzi test Rich Results Google.

Tytuł FAQ dla każdego języka

Jedno pole tytułu na każdy aktywny język witryny, z wartościami domyślnymi dla FR, EN, ES, DE, IT, PT i NL.

Wykluczone kategorie

Lista identyfikatorów kategorii WooCommerce rozdzielonych przecinkami. Produkty z tych kategorii są pomijane w generowaniu masowym i automatycznym (produkty wirtualne, karty podarunkowe itd.).

Metabox FAQ na stronie produktu

Na ekranie edycji każdego produktu metabox FAQ AI daje pełną kontrolę:

• Generuj z AI: tworzy zestaw pytań/odpowiedzi dla wybranego języka.
• Dodaj pytanie ręcznie w dowolnym momencie.
• Edytuj pytanie lub odpowiedź: wiersz zapisuje się automatycznie po utracie fokusu.
• Zmieniaj kolejność przeciągnij-i-upuść za pomocą uchwytu po lewej stronie każdego wiersza.
• Włączaj/wyłączaj wpis bez usuwania.
• Usuń wpis trwale.

Selektor języka u góry metaboxa natychmiast przełącza między tłumaczeniami Polylang lub WPML produktu — każde tłumaczenie ma własny zestaw FAQ.

Generowanie masowe

Menu FAQ AI → Generowanie masowe:

1. Wybierz język docelowy: język domyślny, konkretny język lub wszystkie aktywne języki.
2. Opcjonalnie zaznacz Wymuś ponowne generowanie, aby nadpisać istniejące FAQ (przydatne po zmianie tonu lub dostawcy).
3. Kliknij Start.

Przetwarzanie jest sekwencyjne (około jeden produkt na sekundę w zależności od opóźnień API) z paskiem postępu w czasie rzeczywistym, licznikiem przetworzonych produktów i dziennikiem błędów per produkt. Przycisk Stop przerywa czysto między dwoma produktami. Przetwarzane są tylko opublikowane produkty; kategorie wykluczone są pomijane.

Automatyczne generowanie przy tworzeniu produktu

Opcja w zakładce Dostawca: gdy jest włączona, wtyczka automatycznie generuje FAQ w języku domyślnym przy każdym zapisie produktu, który jeszcze go nie ma. Istniejące FAQ nigdy nie są nadpisywane przez ten mechanizm.

Wielojęzyczność z Polylang i WPML

Wtyczka automatycznie wykrywa Polylang (pll_languages_list, pll_get_post_translations) i WPML (wpml_active_languages, wpml_object_id). Każde tłumaczenie produktu otrzymuje własny zestaw FAQ, generowany natywnie w języku docelowym — a nie tłumaczenie oryginału. Tryb masowy „wszystkie języki” przechodzi przez każde tłumaczenie każdego produktu.

Weryfikacja rich snippets

1. Otwórz stronę produktu z co najmniej jednym aktywnym FAQ.
2. Wyświetl źródło strony i wyszukaj application/ld+json: musi występować blok "@type":"FAQPage".
3. Przetestuj adres URL w teście Rich Results Google: wykrycie „FAQ” musi być poprawne.

Rozwiązywanie problemów

„Klucz API dostawcy AI nie jest skonfigurowany”

Wprowadź klucz aktywnego dostawcy w zakładce Dostawca. Sprawdź, czy przed lub po kluczu nie ma spacji.

Błąd API podczas generowania

Przejdź do WooCommerce → Status → Logi i wybierz źródło dffaqai: każdy błąd API jest tam zapisywany wraz z kodem HTTP i komunikatem dostawcy (nieprawidłowy klucz, przekroczony limit, nieznany model…).

Blok FAQ nie wyświetla się

Sprawdź, czy produkt ma co najmniej jedno aktywne FAQ w wyświetlanym języku i czy motyw wykonuje wybrany hook. W razie wątpliwości wróć do domyślnego hooka woocommerce_after_single_product_summary, obecnego we wszystkich standardowych motywach WooCommerce.

Wygenerowane pytania są w niewłaściwym języku

Język generowania podąża za tłumaczeniem produktu (Polylang/WPML) lub ustawieniami regionalnymi witryny w trybie jednojęzycznym. Sprawdź selektor języka w metaboxie przed generowaniem.

Odinstalowanie

Dezaktywacja zachowuje wszystkie dane. Usunięcie wtyczki uruchamia uninstall.php: tabela SQL z FAQ oraz wszystkie opcje dffaqai_* są trwale usuwane.

Wsparcie

Wsparcie odbywa się e-mailem z odpowiedzią w ciągu 24 godzin roboczych (FR/EN). Jeśli to możliwe, dołącz log dffaqai oraz wersje WordPress/WooCommerce/PHP.