# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/df-llms-aeo/>
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/df-llms-aeo/index.md), [en](https://www.datafirefly.com/en/documentation/df-llms-aeo/index.md), [es](https://www.datafirefly.com/es/documentation/df-llms-aeo/index.md), [de](https://www.datafirefly.com/de/documentation/df-llms-aeo/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-llms-aeo/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-llms-aeo/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-llms-aeo/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## 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](https://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).

**Requisiti:** Shopware 6.7.0+, PHP 8.2+, MySQL 8.0+ o MariaDB 10.6+. Il plugin funziona con lo storefront standard e i temi personalizzati (ereditarietà Twig).

## 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
```

All'attivazione, il plugin installa automaticamente il set di campi personalizzati `datafirefly_aeo` su prodotti, categorie, pagine CMS e produttori. Nessuna migrazione manuale richiesta.

### 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/`).

Il contenuto di `/robots-ai.txt` non viene fuso automaticamente nel vostro `robots.txt` principale. Copiate il suo contenuto nel vostro robots.txt, o aggiungete una regola di riscrittura server (vedere [Integrazione robots.txt](#robots-integrazione)).

## 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." }
  ]
}
```

I campi personalizzati Shopware sono traducibili: compilate la FAQ in ogni lingua tramite il selettore di lingua della scheda prodotto. Il plugin legge il valore nella lingua del contesto della richiesta.

## Dati strutturati Schema.org

Il plugin inietta JSON-LD nel `` 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](https://validator.schema.org/) — incollate l'URL di una scheda prodotto.
- [Google Rich Results Test](https://search.google.com/test/rich-results).

## 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]
```

Usate la riscrittura completa solo se non avete altre direttive robots.txt da preservare (sitemap, esclusioni SEO esistenti). In caso di dubbio, preferite la copia manuale del blocco IA.

## 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](#installazione-assets)) 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.