Documentação do módulo Sitemap XML avançado para PrestaShop (dfsitemap)

O módulo Advanced XML Sitemap (dfsitemap) gera os sitemaps XML do PrestaShop 8 e 9: um índice por loja, um ficheiro por idioma e por tipo de conteúdo, com imagens, vídeos e etiquetas hreflang. Esta página cobre a instalação, as definições, as regras de exclusão, o agendamento e a resolução de problemas.

Instalação

1. Descarregue o ZIP a partir da sua conta de cliente DataFirefly.
2. No back office, vá a Módulos > Gestor de módulos > Carregar um módulo e envie o ZIP.
3. Abra Parâmetros da loja > Tráfego e SEO > Sitemap XML avançado. Três separadores no topo da página dão acesso aos sitemaps e definições, às regras de exclusão e aos vídeos de produto.
4. Se o módulo nativo Google sitemap (gsitemap) estiver ativo, desative-o e apague os seus ficheiros *_sitemap.xml na raiz da loja. O módulo mostra um aviso enquanto o gsitemap estiver ativo.
5. Clique em Gerar agora e depois em Declarar os sitemaps no robots.txt.
6. Submeta o URL de índice apresentado no Google Search Console e no Bing Webmaster Tools.

O módulo funciona do PrestaShop 8.0 ao 9.x com o mesmo ZIP, em multiloja e multilingue. Precisa de escrever na pasta raiz da loja, onde são publicados os ficheiros dfsitemap-*.xml, e em modules/dfsitemap/var/tmp/. Aparece um alerta se uma delas não tiver permissão de escrita.

Os ficheiros gerados

Para cada loja, o módulo publica um índice dfsitemap-{id da loja}-index.xml que aponta para ficheiros com o nome do idioma e do tipo, por exemplo dfsitemap-1-pt-product-1.xml. Quando um ficheiro atinge o número de URL definido, ou antes dos 45 MB, o resto passa para -2, -3, etc. Os URL personalizados sem idioma ficam agrupados em dfsitemap-1-all-custom-1.xml.

Se os URL amigáveis estiverem ativos, o índice é também servido em /sitemap.xml no domínio de cada loja. Um ficheiro físico sitemap.xml na raiz tem prioridade sobre esse endereço: o módulo assinala-o.

Os ficheiros são construídos numa pasta temporária e depois publicados loja a loja. Os sitemaps anteriores continuam online durante a geração, e os ficheiros que deixaram de ser necessários são apagados na publicação.

Definições

As definições seguem o contexto multiloja: no contexto de uma loja, os valores guardados aplicam-se apenas a essa loja.

Conteúdo

• Tipos de conteúdo: páginas estáticas, produtos, categorias, páginas CMS, categorias CMS, marcas, fornecedores, URL personalizados. Só é listado o conteúdo ativo.
• Páginas estáticas: início, mais vendidos, novidades, promoções, listas de marcas e fornecedores, lojas, contacto, mapa do site. As listas de marcas e fornecedores são ignoradas se a sua página estiver desativada nas preferências da loja.
• Idiomas: deixe tudo marcado para seguir automaticamente os idiomas ativos de cada loja.
• Produtos visíveis apenas na pesquisa: por omissão, só são listados os produtos com visibilidade Em todo o lado ou Apenas catálogo.
• URL personalizados: um por linha. Um caminho relativo como /blog/ é acrescentado ao URL da loja.
• Sitemaps adicionais: URL absolutos de sitemaps produzidos noutro local, por exemplo por um módulo de blog ou um WordPress no mesmo domínio. São acrescentados ao índice da loja.

Imagens e vídeos

• Sitemap de imagens e todas as imagens do produto (caso contrário, só a capa), no tamanho de imagem escolhido, large_default por omissão.
• Imagens de categorias, marcas e fornecedores: a imagem original de cada entidade, se existir.
• Sitemap de vídeos e deteção de YouTube e Vimeo: o módulo encontra os vídeos incorporados nas descrições de produto e nas páginas CMS. Os títulos e durações do Vimeo são lidos uma vez e guardados em cache.

Hreflang

• Alternativas hreflang: cada URL lista as suas traduções. Útil assim que a loja tem vários idiomas.
• Código hreflang: idioma e região (pt-PT, a partir do código de idioma definido em Internacional > Idiomas) ou só idioma (pt).
• Idioma x-default: idioma predefinido da loja, um idioma específico ou nenhum.

Etiquetas e apresentação

• lastmod: data da última alteração de produtos, categorias, categorias CMS, marcas e fornecedores.
• changefreq e priority: desativadas por omissão, o Google ignora-as.
• Apresentação legível: uma folha de estilo XSL mostra o índice e os ficheiros como tabela no navegador. Os motores de busca ignoram-na.

Geração

• Frequência: de hora a hora a uma vez por semana, usada pelo cron.
• Regenerar quando o conteúdo muda: quando um produto, categoria, página CMS, marca ou fornecedor é guardado, a chamada cron seguinte regenera sem esperar pela frequência, no máximo uma vez por hora.
• URL por ficheiro: 10 000 por omissão, entre 100 e 50 000.
• Elementos por lote: 50 por omissão. Reduza num servidor lento.
• Tempo máximo por pedido: 20 segundos por omissão, abaixo do max_execution_time do servidor. A partir do back office, cada pedido está limitado a 15 segundos.

Regras de exclusão

O separador Regras de exclusão lista as regras ativas. Cada regra aplica-se a todas as lojas ou a uma só e produz efeito na geração seguinte.

• Produtos: por ID, numa categoria (qualquer associação, subcategorias incluídas), de uma marca, de um fornecedor predefinido, sem stock, com preço zero, sem imagem.
• Categorias: por ID, ou uma categoria com todas as subcategorias. Os produtos continuam listados, salvo se uma regra de produto os retirar.
• Páginas CMS: por ID, ou uma categoria CMS com as suas páginas.
• Marcas e fornecedores: por ID.
• URL contém um texto: um texto por linha, sem distinguir maiúsculas, por exemplo ?q=.
• URL corresponde a uma expressão regular: uma expressão por linha, sem delimitadores, sem distinguir maiúsculas, por exemplo /pt/.*-test$. Uma expressão inválida é recusada ao guardar.

Os ID introduzem-se separados por vírgulas ou quebras de linha. Um URL excluído por uma regra desaparece também das alternativas hreflang das suas traduções.

Vídeos de produto

O separador Vídeos de produto serve para os vídeos alojados fora do YouTube e do Vimeo, ou quando quer um título e uma descrição específicos. Para cada vídeo: o produto (pesquisa por nome, referência ou ID), o título e a descrição por idioma, o URL da miniatura, o URL do ficheiro de vídeo ou o do leitor, a duração em segundos e a loja em causa. Um título vazio num idioma retoma o de outro idioma e, na falta dele, o nome do produto.

Lançar a geração

A partir do back office

Gerar agora lança a geração para as lojas do contexto atual, com uma barra de progresso. A página encadeia os pedidos até ao fim. Se fechar a página, a tarefa fica guardada: o botão Retomar nesta janela continua-a, ou o cron trata dela. Cancelar para a tarefa e os sitemaps online ficam inalterados.

Com o cron

O painel mostra um URL do tipo https://a-sua-loja.pt/module/dfsitemap/cron?token=.... Chame-o a cada 5 minutos a partir do gestor cron do seu alojamento ou do módulo de tarefas cron do PrestaShop. Cada chamada trabalha durante o tempo máximo e a seguinte retoma a tarefa. Uma loja é regenerada quando a sua frequência é atingida, ou após uma alteração de conteúdo se a opção estiver ativa. Parâmetros opcionais: force=1 para regenerar de imediato, id_shop=1,2 para limitar as lojas. O botão Gerar um novo token invalida o URL anterior.

Pela linha de comandos

Com acesso SSH, o script faz toda a tarefa de uma só vez, seja qual for o tamanho do catálogo:

php /caminho/para/prestashop/modules/dfsitemap/cron.php
php /caminho/para/prestashop/modules/dfsitemap/cron.php --force --shop=1

Sem --force, só são regeneradas as lojas cujo prazo chegou. Em caso de erro, o script termina com o código 1.

IndexNow

O IndexNow anuncia uma página criada ou alterada ao Bing, Yandex, Seznam, Naver e aos outros motores do protocolo, sem esperar pela próxima visita. O Google não usa o IndexNow e continua a ler o sitemap.

1. Ative Enviar as páginas alteradas com IndexNow no bloco Indexação instantânea. O módulo escreve um ficheiro de chave na raiz da loja.
2. Sempre que um produto, categoria, página CMS, marca ou fornecedor é guardado, o objeto entra na fila.
3. Na chamada cron seguinte, o módulo calcula os URL desses conteúdos em todos os idiomas e envia-os domínio a domínio. Só é enviado o conteúdo listado no sitemap: um produto inativo ou excluído por uma regra não é enviado.

O bloco IndexNow do painel mostra a fila, a presença do ficheiro de chave e o último envio com o código HTTP (200 ou 202 em caso de sucesso). Perante uma resposta 429 ou 5xx, a fila é mantida para a chamada seguinte. O botão Enviar agora lança um envio imediato.

robots.txt e Search Console

O botão Declarar os sitemaps no robots.txt acrescenta uma linha Sitemap: por loja entre os marcadores # BEGIN dfsitemap e # END dfsitemap. Quando o PrestaShop regenera o robots.txt em Tráfego e SEO, o módulo volta a escrever o bloco. A desinstalação retira-o.

No Google Search Console, submeta o URL de índice de cada loja (ou /sitemap.xml) na propriedade do domínio correspondente.

Multiloja

Cada loja tem o seu índice no próprio domínio, os seus idiomas e as suas definições. Selecione uma loja no menu multiloja para lhe dar valores próprios; no contexto Todas as lojas, os valores aplicam-se às lojas sem valor específico. Para cada loja do contexto, o painel mostra o URL de índice, a data da última geração e o número de URL por tipo, de imagens, vídeos e ficheiros.

Para programadores: acrescentar URL

Um módulo pode acrescentar as suas páginas ao sitemap através do hook actionDfSitemapUrls, chamado durante o tratamento do tipo URL personalizados. O hook recebe id_shop, languages (id_lang => código ISO) e link, e devolve uma lista de entradas:

public function hookActionDfSitemapUrls($params)
{
    $loc = [];
    foreach ($params['languages'] as $idLang => $iso) {
        $loc[$idLang] = $params['link']->getBaseLink($params['id_shop']) . $iso . '/blog/o-meu-artigo';
    }

    return [
        ['loc' => $loc, 'lastmod' => '2026-09-01 10:00:00', 'images' => ['https://.../imagem.jpg']],
        ['loc' => 'https://a-sua-loja.pt/pagina-unica'],
    ];
}

Uma entrada cujo loc está indexado por idioma recebe as etiquetas hreflang como uma página nativa. As entradas inválidas são ignoradas sem interromper a geração.

Perguntas frequentes

O sitemap não contém nenhuma página CMS

Verifique a opção Indexação pelos motores de busca de cada página CMS. Uma página sem ela está em noindex e não é listada.

As marcas ou os fornecedores não aparecem

O módulo segue as preferências da loja: se a página de marcas ou de fornecedores estiver desativada, esse tipo é ignorado.

A geração fica em «Outro processo está a trabalhar na tarefa»

Outro pedido tem o bloqueio, muitas vezes o cron. Se esse pedido foi cortado, o bloqueio expira ao fim do tempo indicado e a geração retoma sozinha.

A geração para com um erro

A mensagem aparece no topo do painel e em Parâmetros avançados > Logs. A causa mais frequente é uma pasta raiz sem permissão de escrita. Os sitemaps anteriores continuam online.

O IndexNow devolve 403 ou 422

O motor não encontra o ficheiro de chave ou recusa o anfitrião. Abra o URL do ficheiro de chave indicado no bloco IndexNow: deve mostrar a chave. Verifique também se o domínio da loja corresponde ao dos URL enviados.