# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-06
- Inne języki: [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), [it](https://www.datafirefly.com/it/documentation/dffaqai/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffaqai/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffaqai/index.md)
- Indeks:
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](https://platform.openai.com/api-keys)) lub Anthropic ([console.anthropic.com](https://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.
Po aktywacji w pasku bocznym panelu pojawia się menu **FAQ AI** z dwiema pozycjami: _Ustawienia_ oraz _Generowanie masowe_.
## 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.
Koszt orientacyjny: wygenerowanie 5 pytań kosztuje około 0,0005 $ z gpt-4o-mini i 0,001 $ z claude-haiku-4-5. Dla 200 produktów w 3 językach łączny koszt to 0,30–0,60 $.
## 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.
Podczas generowania masowego pozostaw kartę przeglądarki otwartą: przetwarzanie jest sterowane z przeglądarki, aby umożliwić pasek postępu i zatrzymanie na żądanie.
## 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](https://search.google.com/test/rich-results): wykrycie „FAQ" musi być poprawne.
Google samodzielnie decyduje o wyświetlaniu rich results w SERP; poprawny znacznik jest warunkiem koniecznym, ale niewystarczającym. Wyświetlanie pojawia się zwykle po ponownym zaindeksowaniu strony.
## 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.