# SERP Tracker: guia completo

> Apresentação O módulo SERP Tracker (dfserptracker) acompanha as posições da sua loja nos resultados de pesquisa do Google, diretamente a partir do back-office do PrestaShop. Declara as suas palavras-chave (com…

- Página: <https://www.datafirefly.com/pt/documentation/dfserptracker/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfserptracker/index.md), [en](https://www.datafirefly.com/en/documentation/dfserptracker/index.md), [es](https://www.datafirefly.com/es/documentation/dfserptracker/index.md), [de](https://www.datafirefly.com/de/documentation/dfserptracker/index.md), [it](https://www.datafirefly.com/it/documentation/dfserptracker/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfserptracker/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfserptracker/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Apresentação

O módulo **SERP Tracker** (`dfserptracker`) acompanha as posições da sua loja nos resultados de pesquisa do Google, diretamente a partir do back-office do PrestaShop. Declara as suas palavras-chave (com o respetivo país e dispositivo), o módulo recolhe regularmente a posição delas através de um **fornecedor de API SERP à sua escolha**, guarda o **histórico** de cada medição, calcula as suas **oportunidades** e **alerta-o por e-mail** quando uma página perde posições.

O SERP Tracker não faz scraping do Google: apoia-se numa API SERP oficial, à qual fornece a sua própria chave. As medições são assim fiáveis, estáveis e conformes com os termos de utilização do Google. São suportados nativamente quatro fornecedores: Serper.dev, ValueSERP, SerpApi e DataForSEO.

## Compatibilidade

- PrestaShop 8.0 a 9.x
- PHP 7.4 a 8.3
- MySQL 5.6+ ou MariaDB 10.3+
- Loja única e multiloja (acompanhamento isolado por loja)
- 5 idiomas: FR, EN, ES, DE, IT
- Compatível com alojamento partilhado
- Sem dependências Composer (autoloader próprio); gráficos gerados com Chart.js embutido localmente, sem CDN

## Instalação

1. No back-office, abra **Módulos > Gestor de módulos**.
2. Clique em **Carregar um módulo** e selecione o ficheiro `dfserptracker.zip`.
3. Depois de instalado, clique em **Configurar**.

Na instalação, o módulo cria as suas duas tabelas (`df_serp_keyword` e `df_serp_position`), regista os seus separadores de administração no menu **SERP Tracker** (Painel, Palavras-chave, Concorrentes) e inicializa as definições predefinidas, entre elas um token de cron aleatório.

## Escolher e configurar um fornecedor SERP

Antes de qualquer medição, tem de escolher um fornecedor e indicar a sua chave de API na página de configuração do módulo.

- **Serper.dev**: indique a sua chave em **Chave API Serper**. Simples e económico, ideal para começar.
- **ValueSERP**: indique a sua chave em **Chave API ValueSERP**.
- **SerpApi**: indique a sua chave em **Chave API SerpApi**.
- **DataForSEO**: este fornecedor usa autenticação por utilizador e palavra-passe. Indique o seu **Login DataForSEO** e a sua **Palavra-passe DataForSEO**.

O módulo é vendido uma única vez; as medições consomem créditos junto do fornecedor que escolher, conforme a sua própria conta e o seu volume de palavras-chave. A maioria dos fornecedores tem uma oferta gratuita ou muito barata para começar.

Aparece um aviso no painel enquanto não houver um fornecedor corretamente configurado. Confirme que a chave introduzida corresponde ao fornecedor selecionado na lista pendente **Fornecedor**.

## Configuração

### Contexto de pesquisa predefinido

- **Domínio acompanhado**: o domínio cuja posição quer detetar (por predefinição, o domínio da loja). O módulo compara este domínio com os resultados orgânicos, ignorando o prefixo `www.`
- **País predefinido** e **Dispositivo predefinido** (computador ou telemóvel): aplicados às novas palavras-chave e substituíveis caso a caso em cada palavra-chave.
- **Profundidade de resultados**: número de resultados analisados por medição (para lá disso, a posição é considerada «não classificada»).

Defina o país predefinido como Portugal e o idioma como português: os resultados do Google variam muito conforme o par país e idioma. Se vende também para o Brasil, crie entradas separadas para as mesmas palavras-chave com o país Brasil, em vez de reutilizar as medições portuguesas, porque as SERP são diferentes.

### Alertas

- **Ativar os alertas**: ativa o envio de e-mails nas mudanças de posição significativas.
- **E-mail de destino**: o endereço que recebe os alertas.
- **Limiar de queda**: número de lugares perdidos a partir do qual é despoletado um alerta.

### Agendamento

- **Dimensão do lote**: número de palavras-chave tratadas em cada passagem do cron.
- **Retenção do histórico**: período de conservação das medições; as mais antigas são eliminadas automaticamente.
- **URL de cron**: endereço só de leitura, protegido por token, a acionar a partir do cron do seu alojamento (ver a secção Medições automáticas).

## Acrescentar e gerir palavras-chave

Abra o separador **Palavras-chave** e depois **Adicionar uma palavra-chave**. Cada palavra-chave tem o seu contexto:

- **Palavra-chave**: a consulta a acompanhar.
- **URL de destino** (facultativo): a página que quer ver posicionada. Se estiver preenchido, o módulo privilegia uma correspondência exata desse URL; caso contrário, retém a primeira página do seu domínio.
- **Etiqueta**: designação de agrupamento (gama, tema) para filtrar as suas palavras-chave.
- **Idioma**, **País** e **Dispositivo**: o contexto de pesquisa próprio dessa palavra-chave.
- **Volume de pesquisa** (facultativo): a título indicativo.
- **Ativa**: só as palavras-chave ativas são medidas pelo cron.

A lista de palavras-chave mostra a posição atual, com uma designação colorida e uma seta de evolução (▲ / ▼) face à medição anterior. A posição **0** significa «não classificada» na profundidade analisada.

Pode fazer uma medição imediata sem esperar pelo cron: use a ação **Verificar agora** numa linha, ou selecione várias palavras-chave e aplique a ação em massa **Verificar**. As ações em massa permitem também ativar, desativar ou eliminar em lote.

Acompanhe as suas palavras-chave com e sem acentos, quando ambas as grafias forem plausíveis: em telemóvel, muitos utilizadores escrevem sem acentos e o Google nem sempre devolve exatamente a mesma SERP para «móveis de jardim» e «moveis de jardim».

## O painel

O separador **Painel** resume o seu posicionamento através de 7 indicadores:

- **Índice de visibilidade** (0 a 100): pontuação global ponderada por uma curva de CTR por posição. Uma palavra-chave em primeiro lugar pesa muito mais do que uma no fundo da página. É o indicador de tendência a seguir ao longo do tempo.
- **Total acompanhado**: número de palavras-chave ativas.
- **Top 3** e **Top 10**: número de palavras-chave posicionadas nos três e nos dez primeiros lugares.
- **Distância ao topo**: palavras-chave posicionadas entre o 4.º e o 20.º lugar, ou seja, as suas oportunidades mais rentáveis.
- **Posição média**: média das posições classificadas.
- **Não classificadas**: palavras-chave que saíram da profundidade analisada.

Por baixo dos indicadores, um **gráfico em anel** mostra a repartição das suas posições (top 3, top 10, distância ao topo, não classificadas). Duas tabelas listam os seus **ganhos** e **perdas** entre as duas últimas medições, e uma tabela de **distância ao topo** isola as palavras-chave com maior potencial. O botão **Executar todas as medições** faz uma medição imediata de todas as palavras-chave em falta (em AJAX, sem sair da página).

## Concorrentes e funcionalidades da SERP

Em cada medição, o módulo deteta as **funcionalidades da SERP**: featured snippet (com identificação do seu proprietário, você ou um concorrente), People Also Ask e local pack.

O separador **Concorrentes** agrega os domínios que aparecem nas suas consultas a partir da última medição de cada palavra-chave, conta o número de aparições e calcula a posição média. São apresentados os 30 domínios mais presentes, para perceber num relance quem o persegue em todo o seu perímetro.

## Medições automáticas (cron)

Para automatizar as medições, acione o URL de cron a partir do agendador de tarefas do seu alojamento. O URL, protegido por um token, é apresentado só de leitura na configuração.

Em cada passagem, o cron trata um lote de palavras-chave em falta (conforme a **dimensão do lote** configurada), espaça as chamadas para respeitar o seu fornecedor e aplica depois a sua duração de **retenção**, eliminando as medições antigas. São aceites dois parâmetros facultativos no URL: `limit` (número de palavras-chave a tratar) e `id_shop` (loja visada, em multiloja).

O token de cron protege o endpoint contra chamadas não autorizadas. Não o divulgue publicamente. Qualquer pedido sem o token correto é rejeitado.

## Alertas

Com os alertas ativos, o SERP Tracker envia um e-mail (modelos HTML e texto, em francês e inglês) quando uma palavra-chave tem uma mudança significativa:

- entrada ou saída do **top 3**;
- saída do **top 10**;
- perda de classificação (a palavra-chave deixa de aparecer);
- queda superior ao **limiar** configurado;
- obtenção de um **featured snippet**.

O e-mail recorda a palavra-chave em causa, a posição anterior e a nova, o motivo ou motivos do alerta e o URL classificado.

Os modelos de e-mail de alerta são fornecidos apenas em francês e inglês. Como estes e-mails são internos e vão para o endereço que indicar, isso não afeta os seus clientes, mas pode traduzi-los criando a pasta `mails/pt` se preferir recebê-los em português.

## Perguntas frequentes e resolução de problemas

### O painel mostra «nenhum fornecedor configurado»

Confirme que selecionou um fornecedor na lista pendente **Fornecedor** e que indicou a chave correspondente (ou o utilizador e a palavra-passe, no caso do DataForSEO). O aviso desaparece assim que é detetado um fornecedor válido.

### As minhas palavras-chave não se atualizam automaticamente

O módulo só mede as posições quando o URL de cron é chamado. Configure uma tarefa agendada no seu alojamento para acionar esse URL com a frequência pretendida (por exemplo, uma vez por dia). Entretanto, o botão **Executar todas as medições** e a ação **Verificar agora** permitem medições manuais.

### Uma posição mostra 0

A posição 0 significa que o seu domínio não foi encontrado na profundidade de resultados analisada. Aumente eventualmente a profundidade na configuração, ou verifique o URL de destino e o contexto (país, dispositivo) da palavra-chave.

### Porque não fazer scraping direto do Google?

O scraping direto é frágil, rapidamente bloqueado e contrário aos termos de utilização do Google. Ao passar por uma API SERP oficial, as medições mantêm-se fiáveis e conformes. Mantém o controlo dos custos através da sua própria conta no fornecedor.

### Como é calculado o índice de visibilidade?

Cada posição é convertida num CTR estimado, através de uma curva por posição, e o conjunto é depois reduzido a uma pontuação de 0 a 100. É um indicador de tendência: sobe quando as suas palavras-chave progridem globalmente para o topo dos resultados.

### É compatível com o PrestaShop 9 e com multiloja?

Sim. O módulo é compatível com PrestaShop 8 e 9, e o acompanhamento é isolado por loja em multiloja. Os controladores apoiam-se em `ModuleAdminController` para se manterem compatíveis entre o PS8 e o PS9.