LLMs.txt & AEO Shopware — Guida completa

Panoramica

DataFirefly LLMs.txt & AEO è un plugin Shopware 6.7 che rende il vostro negozio visibile e comprensibile per i motori di risposta IA (ChatGPT, Claude, Perplexity, Gemini). Agisce su tre piani complementari:

• llms.txt / llms-full.txt — due file conformi alla specifica llmstxt.org, generati automaticamente alla radice di ogni sales-channel, in ogni lingua attiva.
• Schema.org JSON-LD — iniezione automatica di dati strutturati su tutte le pagine: Organization, Product arricchito, BreadcrumbList, FAQPage, HowTo e Speakable.
• Pilotaggio dei crawler IA — un endpoint /robots-ai.txt con controllo individuale di 9 bot (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

Installazione

Via ZIP (consigliato)

1. Scaricate DataFireflyLlmsAeo.zip dal vostro account cliente.
2. Amministrazione Shopware → Estensioni → Le mie estensioni → Carica estensione.
3. Cliccate su Installa, poi Attiva.
4. Svuotate la cache: Impostazioni → Sistema → Cache e indici, o via CLI:

bin/console cache:clear

Via CLI

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

Compilazione degli asset di amministrazione

Se il modulo di amministrazione non appare sotto Marketing dopo l’attivazione:

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

Configurazione

La configurazione si trova in Impostazioni → Sistema → Estensioni → DataFirefly llms.txt & AEO. È delimitata per sales-channel: selezionate un canale specifico nel selettore in alto per sovrascrivere i valori globali.

Scheda «Generale»

• Attiva il modulo — interruttore globale (per sales-channel).
• Autore del sito — usato nell’intestazione del llms.txt.
• Descrizione del sito — blockquote di intestazione del llms.txt; descrivete il vostro negozio in 1-2 frasi orientate all’IA.
• Durata della cache — TTL in secondi (predefinito: 3600).

Scheda «llms.txt»

• Includere le pagine CMS, categorie, marche e/o prodotti.
• Numero massimo di prodotti elencati nell’indice.
• Includere i prodotti inattivi — disattivato per impostazione predefinita; mantenetelo disattivato in produzione.

Scheda «AEO & Schema.org»

• Toggle individuali: Organization, Product arricchito, BreadcrumbList, FAQPage, HowTo, Speakable.
• Logo e URL dell’organizzazione — sovrascrivono i valori del sales-channel.
• Telefono, email di contatto, profili social — alimentano lo schema Organization (contactPoint, sameAs).

Scheda «Crawler IA»

Per ciascuno dei 9 bot, tre modalità:

• Consentito — accesso completo (nessuna direttiva restrittiva).
• Negato — Disallow: / per quel bot.
• Selettivo — Disallow sui percorsi che elencate (uno per riga, es. /checkout/, /account/).

I tre endpoint

URL	Contenuto	Header
/llms.txt	Indice sintetico: Pagine, Categorie, Marche, Prodotti, Optional	text/plain; charset=UTF-8, X-Robots-Tag: noindex, cache pubblica
/llms-full.txt	Contenuto integrale: descrizioni pulite, SKU, EAN, marca, caratteristiche raggruppate, FAQ	idem
/robots-ai.txt	Blocco di direttive User-agent per i 9 crawler IA	idem

Verifica rapida dopo l’installazione:

curl -I https://vostro-negozio.tld/llms.txt
curl -I https://vostro-negozio.tld/llms-full.txt
curl -I https://vostro-negozio.tld/robots-ai.txt

Ogni sales-channel espone i propri file sul proprio dominio, in ogni lingua attiva (gli URL localizzati seguono la configurazione di dominio del canale).

Campi personalizzati AEO

Il set datafirefly_aeo è disponibile su prodotti, categorie, pagine CMS e produttori, nella scheda Campi personalizzati di ogni entità.

Campo	Tipo	Uso
datafirefly_aeo_summary	Testo	Riepilogo di 1-2 frasi usato nel llms.txt al posto della descrizione troncata
datafirefly_aeo_faq	JSON	FAQ strutturata, iniettata come FAQPage JSON-LD
datafirefly_aeo_howto	JSON	Tutorial strutturato, iniettato come HowTo JSON-LD
datafirefly_aeo_speakable	Testo	Testo breve per assistenti vocali (30-40 parole pronunciabili)
datafirefly_aeo_exclude	Booleano	Esclude l’entità dal llms.txt e dal llms-full.txt

Formato del campo FAQ

[
  {
    "q": "Quanto dura la consegna?",
    "a": "La consegna standard richiede da 2 a 4 giorni lavorativi."
  },
  {
    "q": "Qual è la vostra politica di reso?",
    "a": "Avete 30 giorni per restituire un prodotto non utilizzato."
  }
]

Formato del campo HowTo

{
  "name": "Come installare il prodotto",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Preparazione", "text": "Disimballate i componenti." },
    { "name": "Montaggio", "text": "Seguite lo schema fornito." },
    { "name": "Verifica", "text": "Testate il funzionamento." }
  ]
}

Dati strutturati Schema.org

Il plugin inietta JSON-LD nel <head> tramite il template storefront/layout/meta.html.twig (ereditarietà Twig, compatibile con temi personalizzati). Schemi generati:

• Organization — su tutte le pagine: nome, logo, URL, contactPoint, sameAs (profili social).
• Product arricchito — sulle schede prodotto: gtin13 (dall’EAN), mpn, sku, brand (produttore), additionalProperty (caratteristiche raggruppate per gruppo di proprietà), aggregateRating (dalle recensioni native Shopware quando presenti).
• BreadcrumbList — briciole di pane complete della pagina corrente.
• FAQPage — se il campo datafirefly_aeo_faq è compilato sull’entità della pagina.
• HowTo — se il campo datafirefly_aeo_howto è compilato.
• Speakable — selettori CSS h1, .product-detail-name, .product-detail-description-text, .cms-element-text, [data-speakable], più il testo del campo dedicato.

Validazione consigliata dopo la messa in produzione:

• Schema.org Validator — incollate l’URL di una scheda prodotto.
• Google Rich Results Test.

Modulo di amministrazione

Sotto Marketing → DataFirefly llms.txt & AEO:

• Anteprima dal vivo del llms.txt o del llms-full.txt, con rendering monospazio.
• Selettore di sales-channel — visualizzate in anteprima ogni canale in modo indipendente.
• Invalidazione della cache in un clic (per canale o globale).
• Apertura dell’URL pubblico e copia negli appunti.

Comandi CLI e automazione

datafirefly:llms-txt:generate

# Generare il llms.txt di un sales-channel (mostrato in output standard)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Versione completa, scritta in un file, senza passare dalla cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache

datafirefly:llms-txt:warm

# Riscaldare la cache di tutti i sales-channel x tutte le lingue attive
bin/console datafirefly:llms-txt:warm

# Forzare la rigenerazione anche se la cache è ancora valida
bin/console datafirefly:llms-txt:warm --force

# Riscaldare solo il llms.txt (senza il llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full

Cron consigliato

# Riscaldamento giornaliero alle 03:15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet

Un task pianificato Shopware viene anche registrato all’attivazione: se il vostro worker Messenger e lo scheduled task runner sono in esecuzione, la cache si riscalda automaticamente senza cron di sistema.

Integrazione robots.txt

Due approcci per esporre le direttive IA nel vostro robots.txt principale:

Copia manuale

Aprite /robots-ai.txt, copiate il blocco generato e incollatelo nel vostro robots.txt esistente. Da ripetere dopo ogni modifica della configurazione dei bot.

Riscrittura server (consigliata se il robots.txt è gestito interamente dal plugin)

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

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

Cache e prestazioni

• Cache PSR-6 sul pool cache.object di Shopware, taggata datafirefly_llms_aeo.
• Chiavi delimitate per sales-channel + lingua: ogni combinazione ha la propria voce.
• TTL configurabile (predefinito 3600 s).
• Invalidazione: pulsante admin (per canale o globale), comando warm --force, o scadenza naturale.
• Compatibile con cache clusterizzata (Redis): l’invalidazione per tag funziona su tutti gli adattatori taggabili.

Risoluzione dei problemi

Gli endpoint restituiscono 404

1. Verificate che il plugin sia attivato (non solo installato).
2. Svuotate la cache HTTP e la cache dell’applicazione: bin/console cache:clear.
3. Se usate un reverse proxy/CDN, svuotate anche quello.

Errore «Attempted to call an undefined method named getHeader» sulle pagine di navigazione

Bug corretto nella versione 1.0.1: su alcune installazioni Shopware 6.7, NavigationPage non espone getHeader(). Aggiornate alla 1.0.1 (estrazione difensiva della categoria attiva). Se siete già alla 1.0.1 e vedete ancora l’errore, svuotate la cache opcode PHP (opcache_reset o riavvio PHP-FPM).

Il modulo admin non appare sotto Marketing

Compilate gli asset di amministrazione (vedere Installazione) e forzate il ricaricamento del browser (Ctrl+Maiusc+R).

Il llms.txt è vuoto o incompleto

1. Verificate i toggle di inclusione (pagine CMS / categorie / marche / prodotti) nella scheda «llms.txt».
2. Verificate che il limite di prodotti non sia a 0.
3. Controllate il campo datafirefly_aeo_exclude sulle entità assenti.
4. Invalidate la cache e ricaricate.

Il JSON-LD non appare nel codice sorgente

1. Verificate che «Attiva il modulo» e i toggle Schema.org siano attivi per il sales-channel corretto.
2. Se il vostro tema sovrascrive storefront/layout/meta.html.twig senza {{ parent() }} sul blocco interessato, l’iniezione viene persa: ripristinate la chiamata al parent.

Changelog

1.0.1 — 2026-05-21

• Correzione: estrazione difensiva della categoria attiva sulle pagine di navigazione (errore getHeader() su alcune installazioni 6.7).

1.0.0 — 2026-05-21

• Versione iniziale: llms.txt + llms-full.txt, 6 schemi JSON-LD, robots-ai.txt (9 bot), campi personalizzati AEO, modulo admin Vue 3, 2 comandi CLI, task pianificato, snippet FR/EN/DE.