# 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…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffacetedseo/index.md), [en](https://www.datafirefly.com/en/documentation/dffacetedseo/index.md), [es](https://www.datafirefly.com/es/documentation/dffacetedseo/index.md), [de](https://www.datafirefly.com/de/documentation/dffacetedseo/index.md), [it](https://www.datafirefly.com/it/documentation/dffacetedseo/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffacetedseo/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacetedseo/index.md)
- Índice:
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.
As traduções da interface do módulo são fornecidas em francês e em inglês. Para um back-office em português, copie o ficheiro XLIFF como indicado na FAQ técnica mais abaixo; os textos do front-office (chips de filtros, botão Aplicar) seguem o mesmo mecanismo.
## 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](mailto: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.