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 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.

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 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.

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.

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.

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.

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.

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

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.

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"

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.