LLMs.txt i AEO Shopware: kompletny przewodnik

Wprowadzenie

DataFirefly LLMs.txt i AEO to plugin dla Shopware 6.7, który sprawia, że Twój sklep jest widoczny i zrozumiały dla silników odpowiedzi AI (ChatGPT, Claude, Perplexity, Gemini). Działa na trzech uzupełniających się poziomach:

• llms.txt / llms-full.txt: dwa pliki zgodne ze specyfikacją llmstxt.org, generowane automatycznie w katalogu głównym każdego sales-channelu, w każdym aktywnym języku.
• Schema.org JSON-LD: automatyczne wstrzykiwanie danych strukturalnych na wszystkich stronach: Organization, wzbogacony Product, BreadcrumbList, FAQPage, HowTo i Speakable.
• Sterowanie crawlerami AI: endpoint /robots-ai.txt z indywidualną kontrolą 9 botów (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

Instalacja

Przez ZIP (zalecane)

1. Pobierz DataFireflyLlmsAeo.zip ze swojego konta klienta.
2. Administracja Shopware → Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie.
3. Kliknij Zainstaluj, a następnie Aktywuj.
4. Wyczyść cache: Ustawienia → System → Cache i indeksy albo w CLI:

bin/console cache:clear

Przez CLI

unzip DataFireflyLlmsAeo.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyLlmsAeo
bin/console cache:clear

Kompilacja zasobów administracji

Jeśli moduł administracji nie pojawia się w sekcji Marketing po aktywacji:

bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear

Konfiguracja

Konfiguracja znajduje się w Ustawienia → System → Rozszerzenia → DataFirefly llms.txt i AEO. Jest zawężona per sales-channel: wybierz konkretny kanał w selektorze u góry, aby nadpisać wartości globalne.

Karta “Ogólne”

• Włącz moduł: globalny przełącznik (per sales-channel).
• Autor witryny: używany w nagłówku pliku llms.txt.
• Opis witryny: blockquote nagłówka llms.txt; opisz swój sklep w 1-2 zdaniach nakierowanych na AI.
• Czas życia cache: TTL w sekundach (domyślnie: 3600).

Karta “llms.txt”

• Uwzględnij strony CMS, kategorie, marki i/lub produkty.
• Maksymalna liczba produktów wymienionych w indeksie.
• Uwzględnij produkty nieaktywne: domyślnie wyłączone, zostaw wyłączone w produkcji.

Karta “AEO i Schema.org”

• Indywidualne przełączniki: Organization, wzbogacony Product, BreadcrumbList, FAQPage, HowTo, Speakable.
• Logo i adres URL organizacji: nadpisują wartości sales-channelu.
• Telefon, e-mail kontaktowy, profile społecznościowe: zasilają schemat Organization (contactPoint, sameAs).

Karta “Crawlery AI”

Dla każdego z 9 botów trzy tryby:

• Dozwolony: pełny dostęp (żadnej dyrektywy ograniczającej).
• Odmowa: Disallow: / dla tego bota.
• Wybiórczy: Disallow na wypisanych przez Ciebie ścieżkach (jedna na linię, np. /checkout/, /account/).

Trzy endpointy

URL	Zawartość	Nagłówki
/llms.txt	Syntetyczny indeks: Strony, Kategorie, Marki, Produkty, Optional	text/plain; charset=UTF-8, X-Robots-Tag: noindex, cache publiczny
/llms-full.txt	Pełna treść: oczyszczone opisy, SKU, EAN, marka, pogrupowane cechy, FAQ	tak samo
/robots-ai.txt	Blok dyrektyw User-agent dla 9 crawlerów AI	tak samo

Szybka weryfikacja po instalacji:

curl -I https://twoj-sklep.tld/llms.txt
curl -I https://twoj-sklep.tld/llms-full.txt
curl -I https://twoj-sklep.tld/robots-ai.txt

Każdy sales-channel udostępnia własne pliki na swojej domenie, w każdym aktywnym języku (zlokalizowane adresy URL podążają za konfiguracją domen kanału).

Pola niestandardowe AEO

Zestaw datafirefly_aeo jest dostępny na produktach, kategoriach, stronach CMS i producentach, w zakładce Pola niestandardowe każdej encji.

Pole	Typ	Zastosowanie
datafirefly_aeo_summary	Tekst	Podsumowanie w 1-2 zdaniach używane w llms.txt zamiast skróconego opisu
datafirefly_aeo_faq	JSON	Strukturalne FAQ, wstrzykiwane jako FAQPage JSON-LD
datafirefly_aeo_howto	JSON	Strukturalny poradnik, wstrzykiwany jako HowTo JSON-LD
datafirefly_aeo_speakable	Tekst	Krótki tekst dla asystentów głosowych (30-40 słów do wypowiedzenia)
datafirefly_aeo_exclude	Boolean	Wyklucza encję z llms.txt i llms-full.txt

Format pola FAQ

[
  {
    "q": "Ile trwa dostawa?",
    "a": "Dostawa standardowa trwa od 2 do 4 dni roboczych na terenie Polski."
  },
  {
    "q": "Jaka jest polityka zwrotow?",
    "a": "Masz 30 dni na zwrot nieuzywanego produktu."
  }
]

Format pola HowTo

{
  "name": "Jak zainstalowac produkt",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Przygotowanie", "text": "Rozpakuj elementy." },
    { "name": "Montaz", "text": "Postepuj wedlug zalaczonego schematu." },
    { "name": "Sprawdzenie", "text": "Przetestuj dzialanie." }
  ]
}

Dane strukturalne Schema.org

Plugin wstrzykuje JSON-LD do sekcji head przez szablon storefront/layout/meta.html.twig (dziedziczenie Twig, zgodne z motywami niestandardowymi). Generowane schematy:

• Organization: na wszystkich stronach: nazwa, logo, URL, contactPoint, sameAs (profile społecznościowe).
• Wzbogacony Product: na kartach produktów: gtin13 (z EAN), mpn, sku, brand (producent), additionalProperty (cechy pogrupowane po grupach właściwości), aggregateRating (z natywnych opinii Shopware, jeśli są).
• BreadcrumbList: pełna ścieżka nawigacyjna bieżącej strony.
• FAQPage: jeśli pole datafirefly_aeo_faq jest uzupełnione na encji strony.
• HowTo: jeśli pole datafirefly_aeo_howto jest uzupełnione.
• Speakable: selektory CSS h1, .product-detail-name, .product-detail-description-text, .cms-element-text, [data-speakable] oraz tekst z dedykowanego pola.

Zalecana walidacja po wdrożeniu na produkcję:

• Schema.org Validator: wklej adres karty produktu.
• Google Rich Results Test.

Moduł administracji

W Marketing → DataFirefly llms.txt i AEO:

• Podgląd na żywo pliku llms.txt albo llms-full.txt, w renderowaniu monospace.
• Selektor sales-channelu: podglądaj każdy kanał niezależnie.
• Unieważnienie cache jednym kliknięciem (per kanał albo globalnie).
• Otwarcie publicznego adresu URL i kopiowanie do schowka.

Komendy CLI i automatyzacja

datafirefly:llms-txt:generate

# Generate the llms.txt of a sales channel (printed to stdout)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Full version, written to a file, bypassing the cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache

datafirefly:llms-txt:warm

# Warm the cache for all sales channels x all active languages
bin/console datafirefly:llms-txt:warm

# Force regeneration even if the cache is still valid
bin/console datafirefly:llms-txt:warm --force

# Warm only llms.txt (skip llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full

Zalecany cron

# Daily warm-up at 03:15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet

Przy aktywacji rejestrowane jest także zadanie cykliczne Shopware: jeśli Twój worker Messengera i runner zadań cyklicznych działają, cache rozgrzewa się automatycznie, bez crona systemowego.

Integracja robots.txt

Dwa podejścia do udostępnienia dyrektyw AI w Twoim głównym robots.txt:

Ręczne skopiowanie

Otwórz /robots-ai.txt, skopiuj wygenerowany blok i wklej go do istniejącego robots.txt. Do powtórzenia po każdej zmianie konfiguracji botów.

Przepisywanie na serwerze (zalecane, gdy robots.txt jest w całości zarządzany przez plugin)

# nginx
location = /robots.txt {
    rewrite ^ /robots-ai.txt last;
}

# Apache (.htaccess)
RewriteRule ^robots.txt$ /robots-ai.txt [L]

Cache i wydajność

• Cache PSR-6 na puli cache.object Shopware, tagowany datafirefly_llms_aeo.
• Klucze zawężone per sales-channel + język: każda kombinacja ma własny wpis.
• Konfigurowalny TTL (domyślnie 3600 s).
• Unieważnianie: przycisk w administracji (per kanał albo globalnie), komenda warm --force albo naturalne wygaśnięcie.
• Zgodny z cache klastrowanym (Redis): unieważnianie po tagach działa na wszystkich adapterach obsługujących tagi.

Rozwiązywanie problemów

Endpointy zwracają 404

1. Sprawdź, czy plugin jest aktywowany (nie tylko zainstalowany).
2. Wyczyść cache HTTP i cache aplikacji: bin/console cache:clear.
3. Jeśli używasz reverse proxy albo CDN, wyczyść je również.

Błąd “Attempted to call an undefined method named getHeader” na stronach nawigacji

Błąd naprawiony w wersji 1.0.1: na niektórych instalacjach Shopware 6.7 NavigationPage nie udostępnia getHeader(). Zaktualizuj do 1.0.1 (defensywne pobieranie aktywnej kategorii). Jeśli masz już 1.0.1, a błąd nadal występuje, wyczyść cache opcode PHP (opcache_reset albo restart PHP-FPM).

Moduł administracji nie pojawia się w sekcji Marketing

Skompiluj zasoby administracji (zobacz Instalacja), a następnie wymuś przeładowanie przeglądarki (Ctrl+Shift+R).

Plik llms.txt jest pusty albo niekompletny

1. Sprawdź przełączniki uwzględniania (strony CMS / kategorie / marki / produkty) w karcie “llms.txt”.
2. Sprawdź, czy limit produktów nie wynosi 0.
3. Skontroluj pole datafirefly_aeo_exclude na brakujących encjach.
4. Unieważnij cache i przeładuj.

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

1. Sprawdź, czy “Włącz moduł” i przełączniki Schema.org są aktywne dla właściwego sales-channelu.
2. Jeśli Twój motyw nadpisuje storefront/layout/meta.html.twig bez {{ parent() }} w danym bloku, wstrzyknięcie przepada: przywróć wywołanie rodzica.

Changelog

1.0.1, 21.05.2026

• Poprawka: defensywne pobieranie aktywnej kategorii na stronach nawigacji (błąd getHeader() na niektórych instalacjach 6.7).

1.0.0, 21.05.2026

• Wersja początkowa: llms.txt + llms-full.txt, 6 schematów JSON-LD, robots-ai.txt (9 botów), pola niestandardowe AEO, moduł administracji Vue 3, 2 komendy CLI, zadanie cykliczne, snippety FR/EN/DE.