# GSC Connect: documentação
> O GSC Connect traz toda a potência da Google Search Console diretamente para o back-office do PrestaShop: ligação OAuth com um clique, submissão de mapas do site, inspeção de URL…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfgscconnect/index.md), [en](https://www.datafirefly.com/en/documentation/dfgscconnect/index.md), [es](https://www.datafirefly.com/es/documentation/dfgscconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfgscconnect/index.md), [it](https://www.datafirefly.com/it/documentation/dfgscconnect/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfgscconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Índice:
O **GSC Connect** traz toda a potência da Google Search Console diretamente para o back-office do PrestaShop: ligação OAuth com um clique, submissão de mapas do site, inspeção de URL em massa, relatórios de cliques e posições por produto e categoria, e alertas automáticos de queda e de desindexação. Este guia cobre a instalação, a configuração de OAuth da Google, a primeira sincronização, o agendamento do cron, a leitura dos relatórios, a resolução dos erros mais comuns e a arquitetura interna.
## Instalação
O módulo instala-se como qualquer módulo PrestaShop: sem dependências Composer, sem workers persistentes e sem serviços externos além da Google.
1. Descarregue o `dfgscconnect.zip` a partir da sua conta DataFirefly (a ligação de transferência chega depois da encomenda).
2. Back-office → **Módulos → Gestor de módulos → Carregar um módulo**.
3. Arraste o ZIP. O PrestaShop instala automaticamente as 8 tabelas `dfgsc_*`, os separadores de menu e os hooks associados.
4. Clique em **Configurar**, na ficha do módulo.
**Multiloja nativo.** O módulo é multiloja. Cada loja guarda o seu token OAuth, a sua propriedade da Search Console e o seu histórico de métricas. Pode ligar uma loja sem tocar nas outras.
### Pré-requisitos
- PrestaShop 8.0.0 a 9.99.99
- PHP 7.4, 8.0, 8.1, 8.2 ou 8.3
- MySQL 5.6+ ou MariaDB 10.3+
- Extensão PHP `curl` ativa (predefinida em todos os alojamentos)
- Uma conta Google que já tenha acesso de proprietário, ou proprietário delegado, à propriedade da Search Console da sua loja
## Configuração de OAuth da Google
O módulo usa OAuth 2.0 para aceder à Search Console em nome do proprietário da loja. Esta etapa faz-se uma única vez e demora cerca de 5 minutos. Não é preciso qualquer conta de serviço: a autenticação usa diretamente a conta Google que já tem acesso à sua propriedade da Search Console.
### Passo 1: criar um projeto na Google Cloud
1. Vá a [console.cloud.google.com](https://console.cloud.google.com/) com a conta Google que tem acesso à Search Console.
2. Clique no seletor de projeto no topo e depois em **Novo projeto**.
3. Dê-lhe um nome, por exemplo `prestashop-gsc`, e crie-o.
4. Selecione esse novo projeto depois de criado.
### Passo 2: ativar a API da Search Console
1. Menu → **API e Serviços → Biblioteca**.
2. Procure **Google Search Console API**.
3. Clique nela e depois em **Ativar**.
### Passo 3: configurar o ecrã de consentimento
1. Menu → **API e Serviços → OAuth consent screen**.
2. Escolha **External** se a sua conta Google não pertencer a uma organização Google Workspace; caso contrário, **Internal**.
3. Preencha o nome da aplicação (por exemplo, `GSC Connect`), o seu endereço de apoio e o domínio da loja.
4. No ecrã **Scopes**, acrescente o âmbito `https://www.googleapis.com/auth/webmasters` (leitura e escrita na Search Console).
5. No ecrã **Test users**, acrescente o seu endereço Google. Enquanto o ecrã ficar em modo de teste, isso chega para uso privado: não é preciso submeter a aplicação a verificação pela Google.
### Passo 4: criar as credenciais de OAuth
1. Menu → **API e Serviços → Credentials**.
2. **Create Credentials → OAuth client ID**.
3. Tipo de aplicação: **Web application**.
4. Nome: `GSC Connect` (à sua escolha).
5. Em **Origens JavaScript autorizadas**, acrescente o domínio da sua loja com o protocolo HTTPS: `https://a-sua-loja.pt`.
6. Em **URI de redirecionamento autorizado**, cole o URL exato apresentado na configuração do módulo no PrestaShop (caixa do _URL de redirecionamento OAuth_).
7. Clique em **Create**. A Google mostra um **Client ID** e um **Client Secret**.
**O URL de redirecionamento tem de ser exatamente igual.** Incluindo o protocolo (`https`), os subdomínios (com ou sem `www`) e a ausência de barra final. Basta uma diferença para a Google bloquear a ligação com `redirect_uri_mismatch`.
### Passo 5: preencher as credenciais no PrestaShop
1. Back-office → módulo → **Configurar**.
2. Cole o Client ID e o Client Secret.
3. Grave o formulário. Aparece um botão **Ligar com a Google**.
4. Clique nele. É reencaminhado para a página de consentimento da Google.
5. Confirme as permissões e volta ao back-office do PrestaShop.
6. A lista das suas propriedades da Search Console é obtida automaticamente: o módulo seleciona por predefinição a que corresponde ao domínio da sua loja.
## Primeiro arranque
Estabelecida a ligação OAuth, lance a primeira sincronização para trazer os seus dados:
1. Separador **Painel**. A propriedade predefinida já está selecionada.
2. Clique em **Sincronizar agora**. O módulo obtém os últimos 28 dias de dados (cliques, impressões, CTR e posição) ao nível de página e de consulta. Conte entre 30 segundos e 2 minutos, conforme o volume do seu catálogo.
3. Separador **Mapas do site**. Os candidatos são detetados automaticamente (`/sitemap.xml` na raiz e o padrão `*_sitemap.xml` gerado pelo módulo `gsitemap` do PrestaShop). Clique em **Submeter** ao lado de cada mapa relevante.
4. Separador **Inspeção**. Clique em **Colocar em fila todos os produtos ativos**. A fila enche-se de imediato. O processamento real é feito pelo cron, respeitando o limite da Google de 2000 inspeções por dia.
**Latência da Search Console.** A Google disponibiliza os dados do Search Analytics com cerca de 48 h de atraso. Se acabou de se ligar, algumas métricas do dia anterior ou de anteontem ainda não estarão disponíveis. É normal. O módulo tem isso em conta automaticamente no cálculo das quedas (janela deslizante com desvio de 2 dias).
## Painel
O painel reúne 8 indicadores sobre 28 dias:
- **Cliques**: total de cliques orgânicos na janela
- **Impressões**: total de apresentações nos resultados de pesquisa
- **CTR médio**: percentagem de cliques face às impressões
- **Posição média**: posição média ponderada no conjunto das consultas
- **Alertas por ler**: número de alertas abertos a tratar
- **Páginas não indexadas**: número de páginas inspecionadas cujo veredito da Google é FAIL ou NEUTRAL
- **Quota do dia**: chamadas à API de inspeção consumidas do limite diário
- **Última sincronização**: data e hora da última passagem do cron `sync`
Por baixo dos indicadores, um gráfico de evolução de 28 dias mostra os cliques (linha contínua) e as impressões (linha tracejada, em eixo secundário). O Chart.js está incluído localmente, sem qualquer dependência de CDN.
À direita, o **Top 10 de produtos** e o **Top 10 de categorias** ordenam as suas páginas por cliques, com a posição média e o CTR. A resolução de URL para entidade usa o encaminhamento nativo do PrestaShop: padrão `id-slug` nos produtos, `link_rewrite` nas categorias e `cms_lang` nas páginas CMS.
Numa loja multi-idioma, as páginas portuguesas e as de outro idioma aparecem como URL distintos, cada um com as suas métricas. Filtre os relatórios pelo prefixo `/pt/` para avaliar o desempenho da versão portuguesa isoladamente: misturar os idiomas na mesma média esconde precisamente o que quer medir depois de uma tradução.
## Relatórios de cliques e posições
O separador **Relatórios** tem três vistas detalhadas: **Produtos**, **Categorias** e **Consultas**. Cada vista aceita um período configurável: **7, 14, 28 ou 90 dias**.
Em cada linha, obtém os cliques, as impressões, o CTR e a posição média. Clique em qualquer cabeçalho de coluna para ordenar (ordenação no cliente, imediata). A exportação CSV produz um ficheiro UTF-8 com BOM e ponto e vírgula como separador (compatível com o Excel), até 5000 linhas por exportação.
### Comparação de janelas
Em cada produto ou categoria listado, o relatório mostra também a variação face à janela anterior de igual duração. Uma queda de posição significativa aparece a vermelho, e uma melhoria a verde.
A vista de **Consultas** é a mais útil numa loja recém-traduzida: mostra as palavras que os portugueses usam mesmo, que raramente são a tradução literal das francesas. Se aparecer com impressões em consultas que não previu, é sinal de que vale a pena rever o vocabulário das fichas.
## Mapas do site
O separador **Mapas do site** deteta automaticamente os candidatos na sua loja:
- `https://a-sua-loja.pt/sitemap.xml`: mapa do site na raiz
- `https://a-sua-loja.pt/sitemap_index.xml`: índice de mapas do site
- Padrão `*_sitemap.xml` na raiz, gerado pelo módulo `gsitemap` do PrestaShop, com um ficheiro por loja e por idioma
Submeta com um clique. O módulo passa depois a acompanhar por si:
- O número de URL submetidos (declarado pelo seu mapa do site)
- O número de URL efetivamente indexados (comunicado pela Google)
- O número de erros detetados pela Google
- A data da última transferência pelo Googlebot
Se a Google detetar erros num mapa do site, é levantado um alerta automático: gravidade **HIGH** a partir de 10 erros e **MEDIUM** abaixo disso.
O módulo `gsitemap` gera um ficheiro por loja e por idioma: numa loja com português ativo, submeta também o mapa português, e não apenas o do idioma de origem. Sem isso, a Google descobre as páginas portuguesas apenas por ligações internas, o que é bem mais lento.
## Inspeção de URL em massa
A API de URL Inspection da Google está limitada a 2000 chamadas por dia e por propriedade. O GSC Connect gere esse limite com uma fila de espera e repetição automática.
### Ações disponíveis
- **Colocar em fila todos os produtos ativos**: acrescenta todos os produtos com visibilidade `both`, `search` ou `catalog`
- **Colocar em fila todas as categorias**: acrescenta todas as categorias ativas (a raiz fica excluída)
- **Voltar a inspecionar as páginas alteradas**: acrescenta apenas as entidades marcadas como desatualizadas pelos hooks `actionProductUpdate` e `actionCategoryUpdate`
- **Processar a fila agora**: para testes, sem esperar pelo cron
- **Inspecionar um URL avulso**: para validar uma correção imediata numa página concreta
### Dados registados
Em cada URL inspecionado, o módulo regista:
- O veredito global da Google: PASS, PARTIAL, FAIL ou NEUTRAL
- O estado de cobertura (Indexed, Discovered, Crawled but not indexed, entre outros)
- O estado do robots.txt e a indexabilidade declarada
- Os resultados enriquecidos detetados (Product, Breadcrumb, Review, entre outros)
- O estado de AMP e a conformidade com dispositivos móveis
- O mapa do site de referência e os URL de referência
- A data da última exploração pelo Googlebot
**Desindexação detetada, alerta automático.** Se o veredito for FAIL ou NEUTRAL, ou se o estado de cobertura for DEINDEXED ou INDEXING_NOT_ALLOWED, é levantado automaticamente um alerta HIGH, com o motivo devolvido pela Google.
## Alertas e quedas
O módulo trata automaticamente três famílias de alertas:
### Quedas de posição
Deteta uma queda significativa de posição numa página já bem classificada. Por predefinição, uma queda de **5 lugares ou mais** numa página em posição igual ou inferior a 50. O limiar é ajustável na configuração (`DFGSC_DROP_POS`).
### Quedas de cliques
Deteta uma queda significativa do número de cliques numa página que gerava um volume mínimo. Por predefinição, uma queda de **30 %** com um mínimo de **5 cliques** na janela anterior. Os limiares são ajustáveis na configuração (`DFGSC_DROP_CLICKS` e `DFGSC_DROP_MIN_CLICKS`).
### Desindexações
Levantada automaticamente quando um URL inspecionado volta com um veredito FAIL ou NEUTRAL, ou um estado de cobertura DEINDEXED ou INDEXING_NOT_ALLOWED.
### Mecânica de comparação
A comparação de quedas é feita numa janela deslizante de **7 dias** contra os **7 dias anteriores**, com um desvio de 2 dias para respeitar a latência da Search Console. O módulo compara `D-9..D-2` com `D-16..D-9`.
### Eliminação de duplicados em 24 h
Um mesmo alerta (mesma página, mesmo tipo) só é acionado uma vez em cada 24 h, para evitar ruído, mesmo que o cron corra de hora a hora.
### Notificações por e-mail
Os alertas podem ser enviados por e-mail, sob a forma de resumo em HTML agrupado por gravidade, em francês ou em inglês. Ative-os na configuração e indique o endereço de destino.
O resumo só existe em francês e inglês, mas é uma mensagem interna para a sua equipa, não para clientes: aqui, ao contrário de um e-mail transacional, o idioma não é uma questão de conformidade. Traduza-o apenas se a pessoa que recebe os alertas não ler nenhuma das duas línguas.
## Cron e agendamento
Todas as tarefas em segundo plano passam por um endpoint único, protegido por token e visível na página de configuração:
```
https://a-sua-loja.pt/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX
```
Agende-o de 1 em 1 a 6 em 6 horas, no painel de cron do seu alojamento (cPanel, Plesk ou outro). Exemplo de crontab:
```
0 */2 * * * curl -fsS "https://a-sua-loja.pt/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX" > /dev/null 2>&1
```
### Tarefas executadas
Por predefinição, o endpoint executa todas as tarefas. Pode filtrar uma parte com o parâmetro `&tasks=`:
| Tarefa | Ação |
| --- | --- |
| `sync` | Obtenção dos novos dados do Search Analytics (período configurável) |
| `inspect` | Processamento da fila de inspeção de URL, respeitando o limite |
| `sitemaps` | Atualização do estado dos mapas do site submetidos |
| `drops` | Deteção das quedas de posição e de cliques |
| `notify` | Envio do resumo de alertas por e-mail |
| `prune` | Limpeza das entradas de fila terminadas e dos contadores de quota antigos |
Exemplo para sincronizar apenas as métricas, sem tocar na inspeção:
```
curl "https://a-sua-loja.pt/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX&tasks=sync,drops,notify"
```
**Compatível com alojamento partilhado.** Sem dependências de Redis, BullMQ, workers persistentes ou PHP-FPM dedicado. O endpoint do cron é apenas um URL HTTPS protegido por token. Funciona nativamente em qualquer alojamento Linux corrente.
## Configuração de referência
Todas as opções estão na página **Configurar** do módulo:
| Opção | Chave | Predefinição |
| --- | --- | --- |
| Client ID da Google | `DFGSC_CLIENT_ID` | (a preencher) |
| Client Secret da Google | `DFGSC_CLIENT_SECRET` | (a preencher) |
| Período de sincronização (dias) | `DFGSC_LOOKBACK_DAYS` | 28 |
| Quota diária de inspeção de URL | `DFGSC_DAILY_QUOTA` | 2000 |
| Limiar de queda de posição | `DFGSC_DROP_POS` | 5 |
| Limiar de queda de cliques (%) | `DFGSC_DROP_CLICKS` | 30 |
| Cliques mínimos para detetar queda | `DFGSC_DROP_MIN_CLICKS` | 5 |
| Notificações por e-mail ativas | `DFGSC_ALERT_ENABLED` | sim |
| Endereço de destino dos alertas | `DFGSC_ALERT_EMAIL` | e-mail do administrador |
| Token do cron | `DFGSC_CRON_TOKEN` | gerado automaticamente |
## Quotas e limites da API da Google
A API da Search Console é gratuita, mas está sujeita a limites da Google:
- **URL Inspection**: 2000 chamadas por dia e por propriedade, 600 por minuto (limite rígido da Google, não negociável)
- **Search Analytics**: 25 000 linhas por chamada, cerca de 1200 chamadas por minuto e 30 000 por dia (limite indicativo)
- **Mapas do site**: 5000 chamadas por dia
O módulo regista todas as chamadas por endpoint e por dia na tabela `dfgsc_quota`. A fila de inspeção para corretamente quando o limite configurado é atingido, gerando um alerta de gravidade MEDIUM. Os contadores são limpos automaticamente ao fim de 30 dias, pela tarefa `prune`.
## Arquitetura e dados
O módulo segue uma arquitetura PSR-4 clássica, no namespace `DataFireflyGscConnect`, com um autoloader próprio incluído em `vendor/autoload.php`. Sem dependências Composer e sem dependências externas: as chamadas à API da Google são feitas em cURL nativo, com verificação de SSL.
### Camadas
- `Api`: clientes HTTP (GoogleOAuth, SearchConsoleClient)
- `Model`: repositórios de acesso à base (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
- `Services`: orquestração (MetricsSync, Inspection, Sitemap, Alert)
### Tabelas criadas
| Tabela | Função |
| --- | --- |
| `dfgsc_token` | Refresh token de OAuth e expiração, por loja |
| `dfgsc_site` | Propriedades conhecidas da Search Console (por loja, com a predefinida) |
| `dfgsc_metric` | Linhas do Search Analytics (por dia, por página e, opcionalmente, por consulta) |
| `dfgsc_inspection` | Cache local das inspeções de URL, com o veredito completo |
| `dfgsc_sitemap` | Estado dos mapas do site submetidos (URL, submetidos, indexados, erros, última transferência) |
| `dfgsc_alert` | Alertas gerados (tipo, gravidade, página, variação, estado) |
| `dfgsc_queue` | Fila de inspeção, com estados pending, processing, done e failed |
| `dfgsc_quota` | Contadores de chamadas à API por endpoint e por dia |
### Hooks utilizados
- `actionAdminControllerSetMedia`: carregamento dos recursos do back-office
- `displayBackOfficeHeader`: reservado para notificações futuras
- `actionProductUpdate` e `actionCategoryUpdate`: invalidação da cache de inspeção
- `actionObjectProductDeleteAfter` e `actionObjectCategoryDeleteAfter`: limpeza das inspeções órfãs
### Segurança
- Token de estado CSRF em cookie, no fluxo de OAuth
- Validação com `hash_equals` no token do cron
- Refresh token guardado na base e nunca registado em logs
- Access token nunca persistido: é regenerado a pedido a partir do refresh token e mantido em memória durante o pedido
- Ficheiros `index.php` anti-listagem em todos os subdiretórios
- Escape sistemático com `Tools::safeOutput` em todas as saídas dos templates
## Resolução de problemas
### O botão «Ligar com a Google» não aparece
Confirme que o Client ID e o Client Secret estão gravados. Grave o formulário e recarregue a página de configuração.
### O ecrã da Google mostra `redirect_uri_mismatch`
O URI de redirecionamento na Google Cloud tem de ser exatamente igual ao apresentado na configuração do módulo: mesmo protocolo (`https`), mesmo subdomínio (com ou sem `www`), mesmo caminho e sem barra final. Copie e cole sem alterações.
### A sincronização não traz dados
Verifique três pontos: a propriedade selecionada é mesmo a sua loja; tem pelo menos 72 h de histórico na Search Console (a Google publica com cerca de 48 h de latência); e a conta Google ligada tem mesmo acesso de proprietário ou proprietário delegado a essa propriedade.
### As inspeções não são feitas
Confirme que o cron está agendado e que corre. Verifique depois a quota do dia: se consumiu as 2000 chamadas da Google, a fila fica em pausa até ao dia seguinte. Pode forçar manualmente com o botão **Processar a fila agora**.
### Os alertas por e-mail não chegam
Confirme que o endereço indicado é válido, que a configuração de SMTP do PrestaShop funciona (teste com um e-mail de boas-vindas, por exemplo) e que as notificações estão ativas na configuração do módulo.
### Erro 401 ou 403 nas chamadas à Search Console
O refresh token foi provavelmente revogado do lado da Google (mudança de palavra-passe, segurança da conta ou consentimento expirado). Desligue e volte a ligar a loja a partir da configuração.
### Erro `Quota Exhausted` (429)
Foi atingida a quota da Google para a propriedade. Está limitada a 2000 inspeções por dia pela Google, independentemente do número de módulos ou ferramentas que consultem a propriedade. A fila retoma automaticamente no dia seguinte.
## Registo de alterações
Consulte o ficheiro `CHANGELOG.md` incluído no ZIP do módulo, para a lista completa de evoluções por versão.
---
_Para qualquer questão não coberta aqui, contacte o suporte DataFirefly em support@datafirefly.com._