DF Faceted SEO: pesquisa por facetas e SEO PrestaShop

O DF Faceted SEO transforma a pesquisa por facetas do PrestaShop numa alavanca SEO duradoura e acelera as suas páginas de categoria 10 a 30 vezes graças a um índice desnormalizado. Esta documentação cobre a instalação, a configuração das regras de indexação, a criação de landing pages SEO e a exploração das estatísticas de combinações populares.

Apresentação

O módulo nativo ps_facetedsearch gera mecanicamente um URL para cada combinação de filtros possível. Num catálogo de alguns milhares de produtos com cinco facetas, isso representa milhões de URLs que o Google explora, diluindo o seu orçamento de rastreio e o seu PageRank entre páginas quase idênticas.

O DF Faceted SEO resolve este problema de duas formas em paralelo:

• Indexação inteligente: regras de negócio decidem que combinações são indexáveis, quais recebem noindex follow e para onde aponta o canonical.
• Landing pages SEO dedicadas: para as suas combinações com forte potencial comercial (por exemplo « sapatos vermelhos tamanho 42 »), crie páginas de destino com URL limpo, H1, meta e conteúdos personalizados por idioma.

Como bónus, o motor de pesquisa do módulo substitui o motor nativo por um sistema muito mais rápido baseado num índice desnormalizado e numa cache de dois níveis.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 8.1 ou superior
• MySQL 5.7 ou MariaDB 10.3 no mínimo
• URLs amigáveis ativados (Preferências → SEO e URLs)
• Permissões padrão para criação de tabelas MySQL

Instalação

1. Carregue o arquivo ZIP via Módulos → Gestor de módulos → Carregar um módulo.
2. Clique em Instalar. O módulo cria automaticamente 10 tabelas ps_dffacetedseo_* e 5 separadores em Melhorar.
3. Vá a Melhorar → DF Faceted SEO → Painel.
4. Clique em Reconstruir o índice. Este passo é obrigatório na primeira vez: sem índice, o motor de pesquisa do módulo não tem dados para explorar.
5. Limpe a cache do PrestaShop: Parâmetros avançados → Desempenho → Limpar a cache.

Num catálogo de 50 000 produtos, a reconstrução do índice demora tipicamente entre 2 e 5 minutos. O módulo insere as linhas em lotes de 500.

Primeiros passos: painel

O painel (Melhorar → DF Faceted SEO) mostra seis mosaicos estatísticos:

• Regras ativas: número de regras de indexação ativadas
• Landing pages: número de páginas de destino SEO criadas
• Produtos no índice: número de produtos indexados (deve estar próximo do total do catálogo)
• Linhas no índice: número de pares (produto, valor de filtro), ou seja, a tabela desnormalizada
• Entradas em cache: número de pedidos guardados em cache
• Combinações populares: número de combinações de filtros observadas

Sob os mosaicos, dois blocos de operações:

• Reconstruir o índice: útil depois de uma grande alteração de catálogo (importação em massa, mudança de estrutura de atributos)
• Limpar a cache: útil depois de uma alteração de regras ou de parâmetros

Regras de indexação

As regras decidem, para cada combinação de filtros visitada, que etiqueta robots e que canonical são enviados ao navegador e ao Google. Uma regra tem um âmbito (zona de aplicação) e uma política (decisão).

Âmbitos disponíveis

• Global: aplica-se a todas as páginas por facetas do catálogo
• Categoria específica: aplica-se apenas às páginas de uma categoria dada
• Grupo de atributos: aplica-se às combinações que contêm um grupo preciso (por exemplo todas as páginas em que a Cor é filtrada)
• Característica: idem, para uma característica de produto
• Marca: idem, para uma marca (manufacturer)
• Intervalo de preço: aplica-se às páginas filtradas num intervalo tarifário dado

Políticas disponíveis

• Index, follow: página indexável, canonical a apontar para ela própria normalizada
• Noindex, follow: página não indexada, mas as ligações são seguidas (recomendado para as combinações raras)
• Canonical pai: página acessível mas o canonical aponta para a categoria pai (o valor SEO é transferido)
• Canonical self normalizado: canonical na própria página com os filtros ordenados e agrupados (elimina os URLs duplicados para a mesma combinação)

Cadeia de prioridade

O módulo avalia as regras da mais específica para a mais genérica. Concretamente, para uma página da categoria Sapatos filtrada por cor:

1. O módulo procura primeiro uma regra de âmbito category em Sapatos
2. Se existir e corresponder, é aplicada
3. Senão, procura uma regra de âmbito attribute_group em Cor
4. Senão, sobe para a regra global
5. Se nenhuma regra corresponder, é aplicada a política por defeito do painel

Campos avançados de uma regra

• Máximo de filtros indexáveis: se a combinação contiver mais filtros do que este limite, a política passa automaticamente a noindex follow. Exemplo: 2 filtros no máximo nos sapatos (cor + tamanho indexados, mas não cor + tamanho + material + estação).
• Lista branca de valores: IDs de valores autorizados (separados por vírgulas). Uma combinação que contenha apenas valores da lista branca é indexável. Exemplo: autorizar as cores vermelho, preto, branco, azul; as cores raras como « verde-maçã » não serão indexadas.
• Lista negra de valores: o inverso. Qualquer combinação que contenha um valor da lista negra cai automaticamente em noindex.
• Mínimo de produtos: se a combinação não devolver pelo menos este número de produtos, passa a noindex. Evita indexar páginas quase vazias.
• Prioridade: inteiro. Em caso de conflito entre duas regras do mesmo âmbito, ganha a prioridade mais alta.

Estratégia recomendada para começar: crie uma regra global com política canonical pai e máximo de 1 filtro indexável, depois acrescente progressivamente regras mais específicas para abrir a indexação das combinações com forte potencial.

Landing pages SEO

As landing pages são páginas de destino dedicadas a combinações de filtros estratégicas. Têm o seu próprio URL limpo, o seu próprio H1, as suas próprias meta e um conteúdo editorial por idioma.

Criar uma landing page

1. Vá a Melhorar → DF Faceted SEO → Landing pages
2. Clique em Adicionar
3. Secção Segmentação: escolha a categoria e, eventualmente, a marca em causa
4. Secção Apresentação: ordenação por defeito, direção, ativação, indexação, prioridade
5. Secção Combinação de filtros: adicione os filtros que compõem a combinação (grupo de atributos e valores, característica ou marca). Exemplo: Cor = Vermelho E Tamanho = 42.
6. Separadores multilingues: preencha para cada idioma o nome interno, o slug do URL, o H1, o meta title, a meta description, o conteúdo de introdução e o conteúdo de conclusão.
7. Guarde

Estrutura de URL

O URL de uma landing page segue o padrão:

https://o-seu-dominio.pt/landing/o-seu-slug
https://o-seu-dominio.pt/en/landing/o-seu-slug
https://o-seu-dominio.pt/pt/landing/o-seu-slug

O prefixo de idioma é gerido automaticamente pelo router do PrestaShop assim que os URLs amigáveis estão ativados e vários idiomas estão ativos na loja.

Se obtiver um 404 no URL de uma landing, verifique por esta ordem: URLs amigáveis ativados, .htaccess regenerado (botão Guardar no fundo de SEO e URLs), cache limpa, landing ativa no formulário, hook moduleRoutes devidamente ligado ao módulo em Módulos → Posições.

Conteúdo editorial

Para cada idioma, dispõe de dois blocos HTML ricos:

• Introdução: apresentada acima da grelha de produtos. Ideal para um parágrafo de introdução SEO de 150 a 300 palavras com as suas palavras-chave alvo.
• Conclusão: apresentada sob a grelha. Ideal para elementos de confiança, guias de compra, FAQ.

JSON-LD automático

Cada landing page injeta automaticamente dois blocos JSON-LD na página:

• BreadcrumbList: Início → Categoria → Landing
• Product: um bloco Product por produto apresentado (nome, preço, imagem, URL, disponibilidade)

Obtém automaticamente os rich snippets do Google sem configuração adicional.

Estatísticas das combinações populares

O módulo regista automaticamente, na tabela ps_dffacetedseo_combination_log, cada combinação de filtros realmente visitada pelos seus clientes: assinatura, número de hits, última visualização.

Explorar as estatísticas

1. Vá a Melhorar → DF Faceted SEO → Estatísticas
2. Filtre por categoria, número mínimo de hits, limite de apresentação
3. Ordene por hits decrescentes
4. Identifique as combinações com mais de 50 hits por semana
5. Clique em Promover na coluna de ação
6. O formulário de landing page abre pré-preenchido com a combinação de filtros
7. Só tem de preencher o conteúdo editorial e guardar

Manutenção

O fundo da página Estatísticas propõe um botão Purgar os dados antigos com um campo « dias a conservar ». Recomendado: purgar a cada 90 dias para evitar um crescimento ilimitado da tabela.

Parâmetros globais

O painel propõe 11 parâmetros globais agrupados em 3 secções.

Indexação

• Política por defeito: política aplicada quando nenhuma regra corresponde
• Máximo de filtros indexáveis: valor global (pode ser sobreposto por regra)
• Mínimo de produtos por combinação: limiar global para considerar uma página indexável

Desempenho

• TTL da cache (segundos): duração de vida de uma entrada em cache. Por defeito: 3600 (1 hora). Aumente para 86400 (24 h) em produção estável.
• Ocultar os filtros vazios: se ativado, os valores com 0 resultados são ocultados no painel de filtros
• Limite de resultados por página: paginação dos produtos

URLs

• Prefixo dos URLs das landings: por defeito landing. O padrão de rota está definido no hook moduleRoutes do módulo e utiliza este prefixo.

Canonical inteligente

Em cada página por facetas, o módulo calcula o canonical ótimo:

• Combinação que corresponde a uma landing existente: canonical = URL amigável da landing
• Combinação indexável segundo as regras: canonical = self normalizado (filtros ordenados e agrupados)
• Combinação não indexável segundo as regras: canonical = categoria pai
• Página de categoria sem filtro: canonical = self padrão

A normalização agrupa os valores por grupo e ordena os grupos por ID. Dois URLs visualmente diferentes mas semanticamente idênticos (por exemplo com uma ordem diferente dos parâmetros GET) recebem o mesmo canonical.

Motor de filtros de alto desempenho

O motor assenta na tabela ps_dffacetedseo_index: uma linha por trio (produto, tipo de filtro, valor). A pesquisa transforma-se numa interseção de conjuntos de identificadores de produtos.

Cache de dois níveis

• Nível 1: memória (in-process). Evita repetir o mesmo pedido duas vezes na mesma página.
• Nível 2: base de dados (tabela ps_dffacetedseo_cache). Persiste os resultados entre pedidos com TTL.

Invalidação automática

O módulo escuta os hooks actionProductSave, actionProductDelete e actionCategoryUpdate. Sempre que um produto é guardado, a sua entrada no índice é regenerada e todas as entradas de cache ligadas a esse produto são invalidadas.

AJAX e UX

O painel de filtros do front-office é inteiramente controlado em AJAX:

• Debounce de 250 ms nas alterações de filtros
• pushState para atualizar o URL sem recarregar a página
• Atualização em tempo real das etiquetas canonical e robots no cabeçalho do documento
• Scroll suave até à grelha de produtos depois da atualização
• Chips ativos clicáveis para retirar um filtro individual
• Slider de preço com campos numéricos e botão Aplicar
• Swatches de cor visíveis nos atributos do tipo Cor

Multiloja e multilingue

O módulo é nativamente multiloja e multilingue:

• Cada landing page tem traduções por idioma (tabela ps_dffacetedseo_landing_page_lang)
• Cada landing pode ser restringida a uma ou várias lojas (tabela ps_dffacetedseo_landing_page_shop)
• As regras de indexação aplicam-se por defeito a todas as lojas
• O índice é particionado por loja
• As traduções da interface são fornecidas em francês e em inglês (XLIFF em translations/)

Arquitetura técnica

Hooks utilizados

• displayHeader: canonical e meta robots dinâmicos
• actionFrontControllerSetMedia: CSS e JS do front-office
• moduleRoutes: rota limpa para as landing pages
• displayLeftColumn: injeção do painel de filtros
• displayBeforeBodyClosingTag: JSON-LD nas landings
• actionProductSearchProviderRunQuery: integração com o motor PS
• actionProductSave e actionProductDelete: reindexação incremental
• actionCategoryUpdate: invalidação da cache de categoria
• displayBackOfficeHeader: CSS e JS de administração

Tabelas criadas

Tabela	Função
dffacetedseo_rule	Regras de indexação por âmbito
dffacetedseo_landing_page	Landings (dados de negócio)
dffacetedseo_landing_page_lang	Traduções das landings
dffacetedseo_landing_page_shop	Ligações multiloja
dffacetedseo_landing_filter	Filtros associados às landings
dffacetedseo_combination_log	Estatísticas de visita
dffacetedseo_cache	Cache dos resultados de pedidos
dffacetedseo_filter_template	Modelos de filtros reutilizáveis
dffacetedseo_index	Índice desnormalizado (chave do desempenho)
dffacetedseo_setting	Parâmetros internos

Convenção de URL dos filtros

?attribute_group__{id_group}=v1,v2&feature__{id_feature}=v3&manufacturer__0=5&price=10-50&s=needle

É calculada uma assinatura SHA-1 estável para comparar as combinações (correspondência de landing, chave de cache, registo).

Desempenho esperado

Medições realizadas num catálogo de referência (50 000 produtos, 8 facetas ativas):

Motor	Tempo médio
ps_facetedsearch nativo	800 ms a 1,4 s por pedido
DF Faceted SEO sem cache	50 a 120 ms
DF Faceted SEO com cache	menos de 10 ms

Ganho típico: ×10 a ×30

FAQ técnica

É preciso desinstalar o ps_facetedsearch

Não, o módulo integra-se através dos hooks oficiais. Pode testá-lo em paralelo. Uma vez validado, desinstale o ps_facetedsearch para evitar a duplicação do painel de filtros.

O módulo é compatível com HTTPS e URLs canónicos absolutos

Sim. O módulo utiliza Context::getContext()->link->getPageLink() e getModuleLink(), que respeitam a configuração HTTPS do PrestaShop.

Como acrescentar um novo idioma do lado do módulo

Copie o ficheiro translations/fr-FR.xlf para translations/pt-PT.xlf e traduza as trans-unit. Não é necessária nenhuma outra intervenção.

O módulo suporta os atributos compostos (combinações de atributos)

Sim. O índice desnormalizado indexa as declinações através dos seus atributos. O motor de pesquisa filtra os produtos em que pelo menos uma declinação corresponde a todos os filtros ativos.

Como depurar uma regra que não se aplica

Ative os registos do PrestaShop (Parâmetros avançados → Registos) e consulte a secção dffacetedseo. Cada resolução de diretiva regista a regra correspondida e o motivo.

Resolução de problemas

Fatal error numa chamada a getBySlug

Sintoma: Call to a member function getBySlug() on false. Causa: antigo helper get() que devolvia false em vez do objeto de serviço. Corrigido na v1.0.1. Atualize o módulo.

404 no URL de uma landing page

Sintoma: https://o-seu-site/pt/landing/o-seu-slug devolve 404. Causa típica: o hook moduleRoutes não está registado ou a cache de rotas do PrestaShop está desatualizada.

1. Verifique que Preferências → SEO e URLs → Ativar os URLs amigáveis está em SIM
2. Guarde esta página (regenera o .htaccess)
3. Limpe a cache do PrestaShop duas vezes
4. Vá a Módulos → Posições e verifique que dffacetedseo está ligado a moduleRoutes
5. Alternativa de teste: https://o-seu-site/index.php?fc=module&module=dffacetedseo&controller=landing&slug=o-seu-slug

O motor de pesquisa não devolve nenhum produto

O índice está provavelmente vazio. Vá ao painel e clique em Reconstruir o índice.

Os filtros não aparecem na coluna

Verifique em Módulos → Posições que dffacetedseo está ligado ao hook displayLeftColumn. Consoante o seu tema, pode também ligá-lo a displayRightColumn ou displayHome.

Desempenho degradado depois de uma importação massiva de produtos

A invalidação incremental funciona bem para alterações unitárias. Depois de uma importação em massa, é mais rápido reconstruir o índice inteiro a partir do painel e limpar a cache.

Atualizações

O módulo segue um ciclo de versões MAIOR.MENOR.PATCH. As correções críticas (segurança, fatal errors) são fornecidas sob a forma de patch; as novas funcionalidades desencadeiam um incremento menor. Cada atualização maior inclui um script upgrade/upgrade-X.Y.Z.php que é executado automaticamente na instalação da nova versão.

Suporte

Para qualquer questão ou relatório de bug, contacte support@datafirefly.com indicando a versão do PrestaShop, a versão do PHP, a versão do módulo e os registos PHP/PrestaShop.