AI People Also Ask: pełna dokumentacja (dfaipaa)

Prezentacja

AI People Also Ask (slug techniczny: dfaipaa) przechwytuje pytania, które klienci faktycznie zadają Google, czyli bloki „People Also Ask”, generuje odpowiedzi wybraną przez Ciebie AI i publikuje FAQ oznaczone schema.org na kartach produktów i stronach kategorii.

Moduł automatyzuje kompletny pipeline w czterech krokach:

• Scraping: przechwytywanie pytań PAA dla docelowych słów kluczowych przez SerpApi, DataForSEO lub wpis ręczny.
• Generowanie AI: redagowanie odpowiedzi przez Mistral, OpenAI lub Anthropic, z konfigurowalnym tonem i głosem marki.
• Workflow redakcyjny: rewizja, przypisanie do produktów i kategorii, publikacja (ręczna lub automatyczna).
• Publikacja: dostępny akordeon FAQ po stronie sklepu + JSON-LD FAQPage dla Google i silników generatywnych.

Wymagania wstępne

• PrestaShop 8.0.0 → 9.99.99
• PHP 8.1, 8.2 lub 8.3
• MySQL 5.7 / MariaDB 10.4 lub nowsze
• Klucz API do co najmniej jednego dostawcy AI (Mistral, OpenAI lub Anthropic)
• Opcjonalnie: klucz SerpApi lub konto DataForSEO do automatyzacji scrapingu
• Zezwolenie na wychodzące połączenia HTTPS (cURL) z Twojego hostingu

Instalacja

1. Pobierz plik ZIP dfaipaa.zip ze swojego konta DataFirefly.
2. W panelu administracyjnym PrestaShop przejdź do Moduły › Menedżer modułów › Wgraj moduł.
3. Przeciągnij i upuść ZIP, poczekaj na potwierdzenie, a następnie kliknij Zainstaluj.
4. W lewej kolumnie pojawia się nowe menu AI People Also Ask z trzema zakładkami: Konfiguracja, Słowa kluczowe, Pytania.

Instalacja tworzy 4 tabele (prefiks ps_dfaipaa_), ustawia domyślne wartości konfiguracji i instaluje 4 zakładki administracyjne (jedną nadrzędną i trzy podrzędne) z etykietami zlokalizowanymi w FR, EN, ES, DE, IT i NL.

Konfiguracja: scraping

Zakładka AI People Also Ask › Konfiguracja, pierwsza sekcja.

Uzyskanie klucza SerpApi

Załóż konto na serpapi.com. Darmowy plan oferuje 100 zapytań miesięcznie, co odpowiada mniej więcej 100 scrapowanym słowom kluczowym. Klucz znajduje się w panelu, w sekcji „Your Account”. Moduł odpytuje endpoint wyszukiwania Google i wykorzystuje blok related_questions odpowiedzi.

Uzyskanie konta DataForSEO

Załóż konto na dataforseo.com. Otrzymujesz parę login / hasło, którą wklejasz w pole Klucz API w formacie login:password (moduł obsługuje uwierzytelnianie HTTP Basic). DataForSEO rozlicza się według zużycia, co lepiej pasuje do dużych wolumenów. Moduł używa endpointu SERP Google organic live advanced i wyodrębnia elementy people_also_ask.

Mapowanie kodów lokalizacji jest wbudowane dla następujących rynków: FR, BE, CH, LU, CA, US, UK, IE, ES, PT, IT, DE, AT, NL, PL, BR i MX.

Tryb wpisu ręcznego

Wybierz manual, aby wyłączyć wszelkie wywołania zewnętrzne. Pytania dodajesz wtedy samodzielnie z zakładki Pytania; generowanie AI pozostaje w pełni funkcjonalne.

Konfiguracja: sztuczna inteligencja

Druga sekcja zakładki Konfiguracja.

Zalecane modele

• Mistral: mistral-large-latest dla jakości, mistral-small-latest dla obniżenia kosztów przy dużych wolumenach.
• OpenAI: gpt-4o-mini oferuje świetny stosunek jakości do ceny; gpt-4o dla wymagających katalogów technicznych.
• Anthropic: claude-sonnet-4-6 dla zniuansowanych i dobrze ustrukturyzowanych odpowiedzi.

Ograniczenia narzucone modelowi

Moduł buduje rygorystyczny prompt systemowy, niezależny od dostawcy: odpowiedzi od 60 do 120 słów, wyłącznie prosty HTML (akapity, pogrubienie, kursywa, listy), zakaz markdownu, tagów nagłówków i wszelkich skryptów. Kontekst encji (nazwa i opis produktu lub kategorii, przycięte do 1200 znaków) oraz pierwotne słowo kluczowe są wstrzykiwane, aby zakotwiczyć odpowiedź. Oryginalny snippet Google jest podawany jako odniesienie z jawnym poleceniem parafrazy, nigdy kopiowania.

Konfiguracja: wyświetlanie

Trzecia sekcja zakładki Konfiguracja.

W trybie tab moduł opiera się na natywnym mechanizmie ProductExtraContent PrestaShop: FAQ pojawia się jako zakładka obok „Opis” i „Szczegóły produktu”, bez nadpisywania szablonu.

Workflow redakcyjny

Krok 1: dodanie słów kluczowych

Zakładka Słowa kluczowe. Wklej listę w pole tekstowe, jedno słowo kluczowe na linię, i zatwierdź. Duplikaty są ignorowane automatycznie (dodawanie jest idempotentne per słowo kluczowe, język i sklep).

Wybieraj słowa kluczowe odpowiadające intencji zakupowej: „automatyczny ekspres do kawy”, „najlepsza kawa ziarnista”, „czyszczenie ekspresu”. Unikaj zapytań czysto brandowych, które rzadko wywołują bloki PAA.

Krok 2: scraping

Dwie opcje:

• Scrapuj: indywidualny przycisk przy każdym słowie kluczowym, przydatny do testowania konfiguracji.
• Scrapuj wszystkie przeterminowane: przetwarza partiami po 20 słowa kluczowe, których ostatnie pobranie przekracza interwał odświeżania.

Każde przechwycone pytanie jest zapisywane z hashem unikalności (pytanie + język + sklep): ponowny scraping słowa kluczowego nigdy nie tworzy duplikatu, jedynie aktualizuje datę ostatniego pobrania.

Krok 3: generowanie odpowiedzi

Zakładka Pytania. Przefiltruj po statusie pending, zaznacz pytania polami wyboru, a następnie uruchom akcję zbiorczą Generuj. Indywidualny przycisk jest też dostępny przy każdym wierszu.

Kontekst encji jest budowany na podstawie pierwszego przypisania pytania. Aby uzyskać lepsze odpowiedzi, przypisz pytanie do produktu lub kategorii przed generowaniem: AI będzie wtedy dysponować nazwą i opisem encji.

Krok 4: rewizja i przypisanie

Kliknij pytanie, aby otworzyć formularz edycji. Możesz:

• poprawić odpowiedź HTML w edytorze wzbogaconym;
• przypisać pytanie do jednego lub wielu produktów i kategorii (relacja N do N);
• zmienić kolejność przypisań, aby kontrolować kolejność wyświetlania akordeonu;
• odrzucić pytanie nie na temat (status rejected, zachowane w bazie, ale nigdy nie wyświetlane).

Krok 5: publikacja

Zmień status na published. FAQ pojawia się natychmiast po stronie sklepu, wraz ze swoim JSON-LD.

Jeśli w konfiguracji włączona jest opcja Autopublikacja, kroki 4 i 5 są scalane: generowanie publikuje bezpośrednio. Wygodne dla w pełni zautomatyzowanego pipeline’u, do stosowania w katalogach, gdzie ludzka korekta nie jest krytyczna.

Statusy pytań

Wyświetlanie po stronie sklepu

Akordeon opiera się na natywnych elementach HTML details i summary, co gwarantuje:

• działającą nawigację klawiaturą bez JavaScriptu;
• treść indeksowalną przez wyszukiwarki nawet w stanie zwiniętym;
• zgodność ze wszystkimi nowoczesnymi przeglądarkami.

Pierwszy element jest domyślnie otwarty. Ładowany jest lekki plik CSS, w całości możliwy do nadpisania z motywu potomnego. Wszystkie klasy używają prefiksu dfaipaa-faq, aby uniknąć kolizji.

Zdarzenia JavaScript

Skrypt frontowy emituje dwa niestandardowe zdarzenia, które możesz podpiąć do swojego narzędzia analitycznego:

document.addEventListener('dfaipaa:open', function (e) {
  // e.detail.question, e.detail.index, e.detail.type, e.detail.entityId
  gtag('event', 'faq_open', { question: e.detail.question });
});

document.addEventListener('dfaipaa:close', function (e) {
  console.log('FAQ zamknięte:', e.detail.question);
});

Plik views/js/front.js zawiera też stałą SINGLE_OPEN (domyślnie false): ustaw ją na true, aby zezwolić tylko na jeden otwarty panel naraz.

Deep-linking

Kotwica w formie #dfaipaa-q-123 automatycznie otwiera odpowiadające pytanie i przewija stronę do niego. Przydatne do udostępniania konkretnej odpowiedzi z e-maila lub zgłoszenia serwisowego.

Znaczniki JSON-LD FAQPage

Przy każdym załadowaniu strony produktu lub kategorii zawierającej co najmniej jedno opublikowane pytanie moduł wstrzykuje blok JSON-LD tuż przed zamknięciem treści dokumentu (hook displayBeforeBodyClosingTag).

Emitowana struktura: węzeł FAQPage, tablica mainEntity, a dla każdego wpisu węzeł Question zawierający acceptedAnswer typu Answer. Zawartość HTML odpowiedzi jest czyszczona przed emisją: tagi script i style oraz atrybuty zdarzeniowe są usuwane.

Automatyzacja przez cron

Dostarczony skrypt CLI wykonuje pipeline bez ręcznej interwencji.

# Scraping przeterminowanych słów kluczowych (domyślnie maks. 20)
php modules/dfaipaa/cli/cron.php scrape --limit=20

# Generowanie odpowiedzi AI dla oczekujących pytań
php modules/dfaipaa/cli/cron.php generate --limit=10

# Scraping, a następnie generowanie
php modules/dfaipaa/cli/cron.php all --limit=20

Przykładowy crontab, wykonanie nocne o 3:00:

0 3 * * * cd /var/www/prestashop && php modules/dfaipaa/cli/cron.php all --limit=30 >> /var/log/dfaipaa.log 2>&1

Wielojęzyczność i multisklep

Pytania są indeksowane po id_lang i id_shop. W praktyce:

• to samo słowo kluczowe scrapowane po francusku i po angielsku tworzy dwa odrębne zestawy pytań;
• odpowiedzi są generowane w języku pytania, a prompt stosuje jawną dyrektywę językową (fr, en, es, de, it, nl, pt, pl);
• w multisklep pytania i przypisania jednego sklepu nigdy nie pojawiają się w innym;
• tytuły wyświetlania (zakładka, produkt, kategoria) są przechowywane w konfiguracji zlokalizowanej.

Rozwiązywanie problemów

Scraping nie zwraca żadnych pytań

• Sprawdź limit u dostawcy: SerpApi po cichu odcina powyżej darmowego planu.
• Skontroluj spójność języka i kraju: „fr” z „US” daje nieprzewidywalne wyniki.
• Niektóre słowa kluczowe po prostu nie wywołują bloku PAA w Google. Przetestuj zapytanie ręcznie w przeglądarce w trybie prywatnym.
• Dla DataForSEO sprawdź format login:password pola Klucz API.

AI zwraca markdown zamiast HTML

Obniż temperaturę do 0.2 albo przejdź na mocniejszy model. Prompt już narzuca surowe reguły HTML, ale najlżejsze modele mogą je częściowo ignorować.

FAQ nie wyświetla się w sklepie

• Sprawdź, czy co najmniej jedno pytanie ma status published.
• Sprawdź, czy jest przypisane do oglądanej encji (produktu lub kategorii).
• Skontroluj, czy wyświetlanie jest włączone dla tego typu encji w konfiguracji.
• Wyczyść cache Smarty w Zaawansowane › Wydajność.

JSON-LD nie pojawia się w kodzie źródłowym

Upewnij się, że opcja „Emituj JSON-LD” jest włączona i że motyw wywołuje hook displayBeforeBodyClosingTag. Niektóre motywy firm trzecich go pomijają: dodaj wtedy {hook h='displayBeforeBodyClosingTag'} przed zamknięciem treści w swoim layouts/layout-both-columns.tpl.

Błąd „Class not found” po instalacji

Katalog vendor/ nie został rozpakowany. Zainstaluj moduł ponownie, wgrywając ZIP przez panel administracyjny zamiast rozpakowywać ręcznie.

Przeglądanie logów operacji

Wszystkie operacje (scraping, generowanie, publikacja) są rejestrowane. Aby zbadać:

SELECT * FROM ps_dfaipaa_log ORDER BY date_add DESC LIMIT 50;

Odinstalowanie

W Moduły › Menedżer modułów kliknij Odinstaluj. Operacja usuwa 4 tabele ps_dfaipaa_*, 4 zakładki administracyjne i wszystkie klucze konfiguracji DFAIPAA_. Wygenerowana treść jest bezpowrotnie tracona: wyeksportuj wcześniej pytania, jeśli chcesz je zachować.

Referencja techniczna

• Slug techniczny: dfaipaa
• Przestrzeń nazw: DataFirefly Dfaipaa (PSR-4, autoloader wbudowany)
• Tworzone tabele: ps_dfaipaa_keyword, ps_dfaipaa_question, ps_dfaipaa_assignment, ps_dfaipaa_log
• Używane hooki: displayHeader, displayProductExtraContent, displayFooterProduct, displayCategoryFooter, displayBeforeBodyClosingTag, actionFrontControllerSetMedia, actionAdminControllerSetMedia, actionProductUpdate, actionProductSave, actionCategoryUpdate, actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter
• Zakładki panelu: AdminDfaipaa (nadrzędna), AdminDfaipaaConfig, AdminDfaipaaKeywords, AdminDfaipaaQuestions
• Klucze konfiguracji: DFAIPAA_SCRAPER_PROVIDER, DFAIPAA_SCRAPER_API_KEY, DFAIPAA_SCRAPER_LANG, DFAIPAA_SCRAPER_COUNTRY, DFAIPAA_SCRAPER_MAX_PER_KEYWORD, DFAIPAA_AI_PROVIDER, DFAIPAA_AI_MODEL, DFAIPAA_AI_API_KEY, DFAIPAA_AI_TEMPERATURE, DFAIPAA_AI_MAX_TOKENS, DFAIPAA_AI_TONE, DFAIPAA_AI_BRAND_VOICE, DFAIPAA_AUTO_PUBLISH, DFAIPAA_REFRESH_INTERVAL, DFAIPAA_PRODUCT_MODE, DFAIPAA_EMIT_JSONLD, DFAIPAA_TAB_TITLE, DFAIPAA_PRODUCT_TITLE, DFAIPAA_CATEGORY_TITLE
• CLI: modules/dfaipaa/cli/cron.php (polecenia scrape, generate, all)
• Szablon frontowy: views/templates/hook/faq.tpl

Zgodność z RODO

Moduł nie zbiera ani nie przechowuje żadnych danych osobowych: zapisywane są wyłącznie słowa kluczowe, pytania, wygenerowane odpowiedzi i techniczne dzienniki operacji. Po stronie sklepu nie jest umieszczane żadne ciasteczko. Wywołania zewnętrznych API (scraping, AI) przekazują tylko słowo kluczowe, pytanie i kontekst produktu, nigdy dane klientów.

Wsparcie

W razie pytań technicznych skontaktuj się z zespołem DataFirefly pod adresem contact@datafirefly.com lub odwiedź swoją strefę klienta na datafirefly.com.