LLMs.txt e AEO Shopware: guia completo

Apresentação

O DataFirefly LLMs.txt e AEO é uma extensão Shopware 6.7 que torna a sua loja visível e compreensível para os motores de resposta de IA (ChatGPT, Claude, Perplexity, Gemini). Atua em três planos complementares:

• llms.txt / llms-full.txt: dois ficheiros conformes à especificação llmstxt.org, gerados automaticamente na raiz de cada sales channel, em cada idioma ativo.
• Schema.org JSON-LD: injeção automática de dados estruturados em todas as páginas: Organization, Product enriquecido, BreadcrumbList, FAQPage, HowTo e Speakable.
• Controlo dos crawlers de IA: um endpoint /robots-ai.txt com controlo individual de 9 bots (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

Instalação

Por ZIP (recomendado)

1. Transfira o DataFireflyLlmsAeo.zip a partir da sua conta de cliente.
2. Administração do Shopware → Extensões → As minhas extensões → Carregar uma extensão.
3. Clique em Instalar e depois em Ativar.
4. Limpe a cache: Definições → Sistema → Cache e índice, ou por CLI:

bin/console cache:clear

Por CLI

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

Compilação dos recursos de administração

Se o módulo de administração não aparecer em Marketing depois da ativação:

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

Configuração

A configuração encontra-se em Definições → Sistema → Extensões → DataFirefly llms.txt e AEO. Tem âmbito por sales channel: selecione um canal específico no seletor do topo para substituir os valores globais.

Cartão «Geral»

• Ativar o módulo: interruptor global (por sales channel).
• Autor do site: usado no cabeçalho do llms.txt.
• Descrição do site: blockquote de cabeçalho do llms.txt; descreva a sua loja em 1 a 2 frases orientadas para a IA.
• Duração da cache: TTL em segundos (predefinição: 3600).

Cartão «llms.txt»

• Incluir as páginas CMS, categorias, marcas e/ou produtos.
• Número máximo de produtos listados no índice.
• Incluir os produtos inativos: desativado por predefinição, a manter desativado em produção.

Cartão «AEO e Schema.org»

• Interruptores individuais: Organization, Product enriquecido, BreadcrumbList, FAQPage, HowTo, Speakable.
• Logotipo e URL da organização: substituem os valores do sales channel.
• Telefone, email de contacto, perfis sociais: alimentam o esquema Organization (contactPoint, sameAs).

Cartão «Crawlers de IA»

Para cada um dos 9 bots, três modos:

• Autorizado: acesso completo (sem diretiva restritiva).
• Recusado: Disallow: / para esse bot.
• Seletivo: Disallow nos caminhos que listar (um por linha, por exemplo /checkout/, /account/).

Os três endpoints

URL	Conteúdo	Cabeçalhos
/llms.txt	Índice sintético: Páginas, Categorias, Marcas, Produtos, Optional	text/plain; charset=UTF-8, X-Robots-Tag: noindex, cache pública
/llms-full.txt	Conteúdo integral: descrições limpas, SKU, EAN, marca, características agrupadas, FAQ	idem
/robots-ai.txt	Bloco de diretivas User-agent para os 9 crawlers de IA	idem

Verificação rápida após a instalação:

curl -I https://a-sua-loja.tld/llms.txt
curl -I https://a-sua-loja.tld/llms-full.txt
curl -I https://a-sua-loja.tld/robots-ai.txt

Cada sales channel expõe os seus próprios ficheiros no seu próprio domínio, em cada idioma ativo (os URLs localizados seguem a configuração de domínio do canal).

Campos personalizados AEO

O conjunto datafirefly_aeo está disponível nos produtos, categorias, páginas CMS e fabricantes, no separador Campos personalizados de cada entidade.

Campo	Tipo	Utilização
datafirefly_aeo_summary	Texto	Resumo de 1 a 2 frases usado no llms.txt em vez da descrição truncada
datafirefly_aeo_faq	JSON	FAQ estruturada, injetada em FAQPage JSON-LD
datafirefly_aeo_howto	JSON	Tutorial estruturado, injetado em HowTo JSON-LD
datafirefly_aeo_speakable	Texto	Texto curto para assistentes de voz (30 a 40 palavras pronunciáveis)
datafirefly_aeo_exclude	Booleano	Exclui a entidade do llms.txt e do llms-full.txt

Formato do campo FAQ

[
  {
    "q": "Quanto tempo demora a entrega?",
    "a": "A entrega normal demora 2 a 4 dias úteis em Portugal continental."
  },
  {
    "q": "Qual é a vossa política de devolução?",
    "a": "Dispõe de 30 dias para devolver um produto não utilizado."
  }
]

Formato do campo HowTo

{
  "name": "Como instalar o produto",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Preparação", "text": "Desembale os componentes." },
    { "name": "Montagem", "text": "Siga o esquema fornecido." },
    { "name": "Verificação", "text": "Teste o funcionamento." }
  ]
}

Dados estruturados Schema.org

A extensão injeta JSON-LD no <head> através do template storefront/layout/meta.html.twig (herança Twig, compatível com temas personalizados). Esquemas gerados:

• Organization: em todas as páginas: nome, logotipo, URL, contactPoint, sameAs (perfis sociais).
• Product enriquecido: nas páginas de produto: gtin13 (a partir do EAN), mpn, sku, brand (fabricante), additionalProperty (características agrupadas por grupo de propriedades), aggregateRating (a partir das avaliações nativas do Shopware, se existirem).
• BreadcrumbList: caminho de navegação completo da página atual.
• FAQPage: se o campo datafirefly_aeo_faq estiver preenchido na entidade da página.
• HowTo: se o campo datafirefly_aeo_howto estiver preenchido.
• Speakable: seletores CSS h1, .product-detail-name, .product-detail-description-text, .cms-element-text, [data-speakable], mais o texto do campo dedicado.

Validação recomendada depois de ir para produção:

• Schema.org Validator: cole o URL de uma página de produto.
• Google Rich Results Test.

Módulo de administração

Em Marketing → DataFirefly llms.txt e AEO:

• Pré-visualização em direto do llms.txt ou do llms-full.txt, com renderização monoespaçada.
• Seletor de sales channel: pré-visualize cada canal de forma independente.
• Invalidação da cache num clique (por canal ou global).
• Abertura do URL público e cópia para a área de transferência.

Comandos CLI e automatização

datafirefly:llms-txt:generate

# Gerar o llms.txt de um sales channel (apresentado na saída padrão)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Versão completa, escrita num ficheiro, sem passar pela cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache

datafirefly:llms-txt:warm

# Aquecer a cache de todos os sales channels x todos os idiomas ativos
bin/console datafirefly:llms-txt:warm

# Forçar a regeneração mesmo que a cache ainda seja válida
bin/console datafirefly:llms-txt:warm --force

# Aquecer apenas o llms.txt (sem o llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full

Cron recomendado

# Aquecimento diário às 03h15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet

É também registada na ativação uma tarefa agendada do Shopware: se o seu worker Messenger e o scheduled task runner estiverem a correr, a cache aquece automaticamente sem cron de sistema.

Integração no robots.txt

Duas abordagens para expor as diretivas de IA no seu robots.txt principal:

Cópia manual

Abra /robots-ai.txt, copie o bloco gerado e cole-o no seu robots.txt existente. A repetir depois de cada alteração da configuração dos bots.

Reescrita no servidor (recomendada se o robots.txt for inteiramente gerido pela extensão)

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

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

Cache e desempenho

• Cache PSR-6 no pool cache.object do Shopware, com a tag datafirefly_llms_aeo.
• Chaves com âmbito por sales channel e idioma: cada combinação tem a sua própria entrada.
• TTL configurável (predefinição 3600 s).
• Invalidação: botão na administração (por canal ou global), comando warm --force, ou expiração natural.
• Compatível com cache em cluster (Redis): a invalidação por tags funciona em todos os adaptadores com suporte a tags.

Resolução de problemas

Os endpoints devolvem 404

1. Verifique que a extensão está mesmo ativa (não apenas instalada).
2. Limpe a cache HTTP e a cache de aplicação: bin/console cache:clear.
3. Se usar um proxy inverso ou CDN, limpe-o também.

Erro «Attempted to call an undefined method named getHeader» nas páginas de navegação

Erro corrigido na versão 1.0.1: em algumas instalações Shopware 6.7, a NavigationPage não expõe getHeader(). Atualize para a 1.0.1 (extração defensiva da categoria ativa). Se já estiver na 1.0.1 e continuar a ver o erro, limpe a cache de opcode do PHP (opcache_reset ou reinício do PHP-FPM).

O módulo de administração não aparece em Marketing

Compile os recursos de administração (ver Instalação) e force o recarregamento do navegador (Ctrl+Shift+R).

O llms.txt está vazio ou incompleto

1. Verifique os interruptores de inclusão (páginas CMS / categorias / marcas / produtos) no cartão «llms.txt».
2. Verifique que o limite de produtos não está a 0.
3. Controle o campo datafirefly_aeo_exclude nas entidades ausentes.
4. Invalide a cache e recarregue.

O JSON-LD não aparece no código-fonte

1. Verifique que «Ativar o módulo» e os interruptores Schema.org estão ativos para o sales channel certo.
2. Se o seu tema sobrepuser storefront/layout/meta.html.twig sem {{ parent() }} no bloco em causa, a injeção perde-se: reponha a chamada ao bloco pai.

Changelog

1.0.1, 2026-05-21

• Correção: extração defensiva da categoria ativa nas páginas de navegação (erro getHeader() em algumas instalações 6.7).

1.0.0, 2026-05-21

• Versão inicial: llms.txt e llms-full.txt, 6 esquemas JSON-LD, robots-ai.txt (9 bots), campos personalizados AEO, módulo de administração em Vue 3, 2 comandos CLI, tarefa agendada, snippets FR/EN/DE.