# LLMs.txt & AEO Shopware — Guide complet

> Présentation DataFirefly LLMs.txt & AEO est un plugin Shopware 6.7 qui rend votre boutique visible et compréhensible par les moteurs de réponse IA (ChatGPT, Claude, Perplexity, Gemini). Il agit sur…

- Page: <https://www.datafirefly.com/documentation/df-llms-aeo/>
- Langue: fr
- Mis à jour le: 2026-07-01
- Autres langues: [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), [it](https://www.datafirefly.com/it/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)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

## Présentation

DataFirefly LLMs.txt & AEO est un plugin Shopware 6.7 qui rend votre boutique visible et compréhensible par les moteurs de réponse IA (ChatGPT, Claude, Perplexity, Gemini). Il agit sur trois plans complémentaires :

- **llms.txt / llms-full.txt** — deux fichiers conformes à la spécification [llmstxt.org](https://llmstxt.org), générés automatiquement à la racine de chaque sales-channel, dans chaque langue active.
- **Schema.org JSON-LD** — injection automatique de données structurées sur toutes les pages : Organization, Product enrichi, BreadcrumbList, FAQPage, HowTo et Speakable.
- **Pilotage des crawlers IA** — un endpoint `/robots-ai.txt` avec contrôle individuel de 9 bots (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

**Prérequis :** Shopware 6.7.0+, PHP 8.2+, MySQL 8.0+ ou MariaDB 10.6+. Le plugin fonctionne sur le storefront standard et les thèmes personnalisés (héritage Twig).

## Installation

### Via ZIP (recommandé)

1. Téléchargez `DataFireflyLlmsAeo.zip` depuis votre compte client.
2. Administration Shopware → **Extensions → Mes extensions → Téléverser une extension**.
3. Cliquez sur **Installer**, puis **Activer**.
4. Videz le cache : **Paramètres → Système → Cache & index**, ou en 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
```

À l'activation, le plugin installe automatiquement le set de champs personnalisés `datafirefly_aeo` sur les produits, catégories, pages CMS et fabricants. Aucune migration manuelle n'est nécessaire.

### Compilation des assets administration

Si le module d'administration n'apparaît pas sous Marketing après activation :

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

## Configuration

La configuration se trouve dans **Paramètres → Système → Extensions → DataFirefly llms.txt & AEO**. Elle est scopée par sales-channel : sélectionnez un canal spécifique dans le sélecteur en haut pour surcharger les valeurs globales.

### Carte « Général »

- **Activer le module** — interrupteur global (par sales-channel).
- **Auteur du site** — utilisé dans l'en-tête du llms.txt.
- **Description du site** — blockquote d'en-tête du llms.txt ; décrivez votre boutique en 1-2 phrases orientées IA.
- **Durée du cache** — TTL en secondes (défaut : 3600).

### Carte « llms.txt »

- Inclure les **pages CMS**, **catégories**, **marques** et/ou **produits**.
- **Nombre maximum de produits** listés dans l'index.
- **Inclure les produits inactifs** — désactivé par défaut, à laisser désactivé en production.

### Carte « AEO & Schema.org »

- Toggles individuels : Organization, Product enrichi, BreadcrumbList, FAQPage, HowTo, Speakable.
- **Logo et URL de l'organisation** — surchargent les valeurs du sales-channel.
- **Téléphone, email de contact, profils sociaux** — alimentent le schéma Organization (`contactPoint`, `sameAs`).

### Carte « Crawlers IA »

Pour chacun des 9 bots, trois modes :

- **Autorisé** — accès complet (aucune directive restrictive).
- **Refusé** — `Disallow: /` pour ce bot.
- **Sélectif** — `Disallow` sur les chemins que vous listez (un par ligne, ex. `/checkout/`, `/account/`).

Le contenu de `/robots-ai.txt` n'est pas fusionné automatiquement dans votre `robots.txt` principal. Copiez son contenu dans votre robots.txt, ou ajoutez une règle de réécriture serveur (voir la section [Intégration robots.txt](#robots-integration)).

## Les trois endpoints

| URL | Contenu | En-têtes |
| --- | --- | --- |
| `/llms.txt` | Index synthétique : Pages, Catégories, Marques, Produits, Optional | `text/plain; charset=UTF-8`, `X-Robots-Tag: noindex`, cache public |
| `/llms-full.txt` | Contenu intégral : descriptions nettoyées, SKU, EAN, marque, caractéristiques groupées, FAQ | idem |
| `/robots-ai.txt` | Bloc de directives User-agent pour les 9 crawlers IA | idem |

Vérification rapide après installation :

```
curl -I https://votre-boutique.tld/llms.txt
curl -I https://votre-boutique.tld/llms-full.txt
curl -I https://votre-boutique.tld/robots-ai.txt
```

Chaque sales-channel expose ses propres fichiers sur son propre domaine, dans chaque langue active (les URL localisées suivent la configuration de domaine du canal).

## Champs personnalisés AEO

Le set `datafirefly_aeo` est disponible sur les **produits, catégories, pages CMS et fabricants**, dans l'onglet Champs personnalisés de chaque entité.

| Champ | Type | Usage |
| --- | --- | --- |
| `datafirefly_aeo_summary` | Texte | Résumé 1-2 phrases utilisé dans le llms.txt à la place de la description tronquée |
| `datafirefly_aeo_faq` | JSON | FAQ structurée, injectée en FAQPage JSON-LD |
| `datafirefly_aeo_howto` | JSON | Tutoriel structuré, injecté en HowTo JSON-LD |
| `datafirefly_aeo_speakable` | Texte | Texte court pour assistants vocaux (30-40 mots énonçables) |
| `datafirefly_aeo_exclude` | Booléen | Exclut l'entité du llms.txt et du llms-full.txt |

### Format du champ FAQ

```
[
  {
    "q": "Combien de temps dure la livraison ?",
    "a": "La livraison standard prend 2 à 4 jours ouvrés en France métropolitaine."
  },
  {
    "q": "Quelle est votre politique de retour ?",
    "a": "Vous disposez de 30 jours pour retourner un produit non utilisé."
  }
]
```

### Format du champ HowTo

```
{
  "name": "Comment installer le produit",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Préparation", "text": "Déballez les composants." },
    { "name": "Montage", "text": "Suivez le schéma fourni." },
    { "name": "Vérification", "text": "Testez le fonctionnement." }
  ]
}
```

Les champs personnalisés Shopware sont traduisibles : renseignez la FAQ dans chaque langue via le sélecteur de langue de la fiche produit. Le plugin lit la valeur dans la langue du contexte de la requête.

## Données structurées Schema.org

Le plugin injecte du JSON-LD dans le `` via le template `storefront/layout/meta.html.twig` (héritage Twig, compatible thèmes personnalisés). Schémas générés :

- **Organization** — sur toutes les pages : nom, logo, URL, `contactPoint`, `sameAs` (profils sociaux).
- **Product enrichi** — sur les fiches produit : `gtin13` (depuis l'EAN), `mpn`, `sku`, `brand` (fabricant), `additionalProperty` (caractéristiques groupées par groupe de propriétés), `aggregateRating` (depuis les avis natifs Shopware si présents).
- **BreadcrumbList** — fil d'Ariane complet de la page courante.
- **FAQPage** — si le champ `datafirefly_aeo_faq` est renseigné sur l'entité de la page.
- **HowTo** — si le champ `datafirefly_aeo_howto` est renseigné.
- **Speakable** — sélecteurs CSS `h1`, `.product-detail-name`, `.product-detail-description-text`, `.cms-element-text`, `[data-speakable]`, plus le texte du champ dédié.

Validation recommandée après mise en production :

- [Schema.org Validator](https://validator.schema.org/) — coller l'URL d'une fiche produit.
- [Google Rich Results Test](https://search.google.com/test/rich-results).

## Module d'administration

Sous **Marketing → DataFirefly llms.txt & AEO** :

- **Prévisualisation en direct** du llms.txt ou du llms-full.txt, avec rendu monospace.
- **Sélecteur de sales-channel** — prévisualisez chaque canal indépendamment.
- **Invalidation du cache** en un clic (par canal ou globale).
- **Ouverture de l'URL publique** et **copie dans le presse-papier**.

## Commandes CLI et automatisation

### datafirefly:llms-txt:generate

```
# Générer le llms.txt d'un sales-channel (affiché en sortie standard)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Version complète, écrite dans un fichier, sans passer par le cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache
```

### datafirefly:llms-txt:warm

```
# Réchauffer le cache de tous les sales-channels x toutes les langues actives
bin/console datafirefly:llms-txt:warm

# Forcer la régénération même si le cache est encore valide
bin/console datafirefly:llms-txt:warm --force

# Ne réchauffer que le llms.txt (sans le llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full
```

### Cron recommandé

```
# Réchauffement quotidien à 03h15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet
```

Une **tâche planifiée Shopware** est également enregistrée à l'activation : si votre worker Messenger et le scheduled task runner tournent, le cache se réchauffe automatiquement sans cron système.

## Intégration robots.txt

Deux approches pour exposer les directives IA dans votre robots.txt principal :

### Copie manuelle

Ouvrez `/robots-ai.txt`, copiez le bloc généré et collez-le dans votre robots.txt existant. À refaire après chaque changement de configuration des bots.

### Réécriture serveur (recommandé si robots.txt entièrement géré par le plugin)

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

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

N'utilisez la réécriture complète que si vous n'avez pas d'autres directives robots.txt à préserver (sitemap, exclusions SEO existantes). Dans le doute, préférez la copie manuelle du bloc IA.

## Cache et performances

- Cache **PSR-6** sur le pool `cache.object` de Shopware, tagué `datafirefly_llms_aeo`.
- Clés scopées par **sales-channel + langue** : chaque combinaison a sa propre entrée.
- TTL configurable (défaut 3600 s).
- Invalidation : bouton admin (par canal ou globale), commande `warm --force`, ou expiration naturelle.
- Compatible cache clusterisé (Redis) : l'invalidation par tags fonctionne sur tous les adaptateurs taggables.

## Dépannage

### Les endpoints renvoient 404

1. Vérifiez que le plugin est bien **activé** (pas seulement installé).
2. Videz le cache HTTP et le cache d'application : `bin/console cache:clear`.
3. Si vous utilisez un reverse proxy/CDN, purgez-le également.

### Erreur « Attempted to call an undefined method named getHeader » sur les pages de navigation

Bug corrigé en **version 1.0.1** : sur certaines installations Shopware 6.7, `NavigationPage` n'expose pas `getHeader()`. Mettez à jour vers la 1.0.1 (extraction défensive de la catégorie active). Si vous êtes déjà en 1.0.1 et voyez encore l'erreur, videz le cache d'opcode PHP (`opcache_reset` ou redémarrage PHP-FPM).

### Le module admin n'apparaît pas sous Marketing

Compilez les assets d'administration (voir [Installation](#installation-assets)) puis forcez le rechargement du navigateur (Ctrl+Maj+R).

### Le llms.txt est vide ou incomplet

1. Vérifiez les toggles d'inclusion (pages CMS / catégories / marques / produits) dans la carte « llms.txt ».
2. Vérifiez que la limite de produits n'est pas à 0.
3. Contrôlez le champ `datafirefly_aeo_exclude` sur les entités absentes.
4. Invalidez le cache puis rechargez.

### Le JSON-LD n'apparaît pas dans le code source

1. Vérifiez que « Activer le module » et les toggles Schema.org sont actifs pour le bon sales-channel.
2. Si votre thème surcharge `storefront/layout/meta.html.twig` sans `{{ parent() }}` sur le block concerné, l'injection est perdue : rétablissez l'appel parent.

## Changelog

### 1.0.1 — 2026-05-21

- Correctif : extraction défensive de la catégorie active sur les pages de navigation (erreur `getHeader()` sur certaines installations 6.7).

### 1.0.0 — 2026-05-21

- Version initiale : llms.txt + llms-full.txt, 6 schémas JSON-LD, robots-ai.txt (9 bots), champs personnalisés AEO, module admin Vue 3, 2 commandes CLI, tâche planifiée, snippets FR/EN/DE.