dfsearchconsole: Google Search Console para PrestaShop

Apresentação

O dfsearchconsole sincroniza os dados da Google Search Console diretamente no back-office PrestaShop 8 e 9: principais pesquisas por URL, CTR por página, posição média e, sobretudo, quatro categorias de oportunidades SEO calculadas automaticamente com sugestões de otimização contextuais.

O módulo acrescenta 5 separadores em Melhorar → Search Console: Painel, Páginas, Pesquisas, Oportunidades e Parâmetros. A comunicação com a Google é feita via OAuth2 em modo só de leitura (âmbito webmasters.readonly), sem dependência Composer: apenas cURL nativo.

Instalação

1. Descarregue o ficheiro ZIP do módulo a partir da sua conta de cliente DataFirefly.
2. No back-office PrestaShop: Módulos → Gestor de módulos → Carregar um módulo.
3. Selecione o ficheiro ZIP e deixe a instalação terminar.
4. O módulo cria 4 tabelas SQL (ps_dfgsc_sync, ps_dfgsc_page, ps_dfgsc_query, ps_dfgsc_opportunity) e regista os seus 5 separadores sob o menu Melhorar.

Configuração OAuth Google Cloud

O módulo comunica com a API Search Console através das suas próprias credenciais OAuth2. A criação é gratuita e demora cerca de dez minutos.

1. Criar o projeto e ativar a API

1. Vá a console.cloud.google.com e crie um projeto (ou reutilize um).
2. Em APIs e serviços → Biblioteca, procure Google Search Console API e ative-a.

2. Configurar o ecrã de consentimento

1. Abra APIs e serviços → Ecrã de consentimento OAuth.
2. Tipo de utilizador: Externo (ou Interno se usar o Google Workspace).
3. Preencha o nome da aplicação, o e-mail de suporte e o seu domínio.
4. Adicione o âmbito https://www.googleapis.com/auth/webmasters.readonly.
5. Enquanto a aplicação não estiver publicada, adicione o seu endereço Google como utilizador de teste.

3. Criar o ID de cliente OAuth

1. Em APIs e serviços → Credenciais, clique em Criar credenciais → ID de cliente OAuth.
2. Tipo de aplicação: Aplicação Web.
3. Em URIs de redirecionamento autorizados, cole o URL apresentado no ecrã Parâmetros do módulo (na forma https://o-seu-dominio.pt/module/dfsearchconsole/oauth).
4. Anote o Client ID e o Client Secret.

4. Ligar o módulo

1. No PrestaShop, abra Melhorar → Search Console → Parâmetros.
2. Cole o Client ID e o Client Secret e guarde.
3. Clique em Ligar à Google e autorize o acesso.
4. De volta ao back-office, selecione a propriedade Search Console a sincronizar na lista pendente.

Sincronização

Sincronização manual

O botão Sincronizar agora do ecrã Parâmetros lança imediatamente uma sincronização completa. Conte alguns segundos para uma loja pequena a 2-3 minutos para um site com milhares de páginas indexadas.

Sincronização automática (cron)

O ecrã Parâmetros mostra um URL de cron protegido por um token aleatório de 32 caracteres. Adicione-o ao seu crontab para uma sincronização diária:

0 4 * * * curl -s "https://o-seu-dominio.pt/module/dfsearchconsole/cron?token=O_SEU_TOKEN" > /dev/null

Período de lookback

Por defeito, o módulo recupera 90 dias de dados e os 90 dias anteriores para calcular os deltas. Este período é configurável de 28 a 480 dias em Parâmetros. Quanto maior a janela, mais longa a sincronização.

Painel

O painel dá uma visão geral: 4 cartões KPI (cliques, impressões, CTR, posição média) com as evoluções em relação ao período anterior, o top 10 das páginas, o top 15 das pesquisas e uma pré-visualização das oportunidades prioritárias.

Páginas e Pesquisas

Separador Páginas

Lista paginada e ordenável de todos os URLs devolvidos pela Search Console, com cliques, impressões, CTR, posição e delta de cliques. Um filtro permite restringir por tipo de página (produto, categoria, CMS, outro) ou por texto. Clicar num URL abre a sua vista de detalhe: KPI da página com valores do período anterior, pesquisas que visam esse URL, oportunidades associadas e ligação direta para a edição da entidade PrestaShop correspondente.

Separador Pesquisas

Dois modos de apresentação:

• Vista agrupada: uma linha por pesquisa, agregada em todos os URLs. Ideal para identificar os seus termos principais.
• Vista detalhada: uma linha por par pesquisa × URL. Indispensável para analisar a canibalização.

As posições são apresentadas com um código de cores: verde (1-3), azul (4-10), amarelo (11-20, impulsionáveis), cinzento (21+).

Oportunidades SEO

Depois de cada sincronização, o módulo recalcula automaticamente quatro categorias de oportunidades:

• Top 11–20 impulsionáveis (striking distance): pesquisas posicionadas entre 11 e 20 (limiares configuráveis) com um mínimo de impressões. O módulo calcula o ganho potencial de cliques simulando uma passagem à posição 5.
• CTR abaixo da média (top 10): páginas no top 10 cujo CTR real é inferior a 50 % do CTR esperado segundo a curva de referência integrada (agregada de estudos Advanced Web Ranking, Sistrix, Backlinko).
• Canibalização: a mesma pesquisa a devolver 2 ou mais URLs. O módulo lista os URLs concorrentes.
• Perda de cliques: páginas que perderam mais de 25 % de cliques face ao período anterior.

Cada oportunidade mostra uma pontuação de prioridade, as métricas associadas e sugestões de otimização adaptadas ao tipo de página (ficha de produto, categoria ou página CMS). O fluxo Aberta / Tratada / Ignorada permite acompanhar o seu progresso. O botão Recalcular refaz todas as oportunidades a partir dos dados já na base de dados, sem voltar a chamar a API Google.

Definição dos limiares

Em Parâmetros, três limiares controlam a deteção:

• Impressões mínimas (por defeito 50): abaixo disso, o par pesquisa × URL é ignorado pelos detetores.
• Posição mín. / máx. striking distance (por defeito 11 / 20): a janela de posições considerada impulsionável.

Para uma loja pequena com pouco tráfego, baixe o limiar de impressões para 20-30. Para um site grande, suba-o para 100+ para só fazer subir os trabalhos significativos.

Resolução de problemas

« Token expirado » ou erro 401

O refresh token é usado automaticamente de hora a hora. Se a Google tiver revogado o acesso (mudança de palavra-passe, longa inatividade, revogação manual), volte a ligar o módulo através do botão Ligar à Google do ecrã Parâmetros.

Nenhum site na lista pendente

A conta Google ligada deve ter acesso a pelo menos uma propriedade Search Console (proprietário ou utilizador). Verifique em search.google.com/search-console com a mesma conta.

Erro « redirect_uri_mismatch » na ligação

O URI de redirecionamento declarado na Google Cloud Console deve corresponder exatamente ao apresentado no ecrã Parâmetros do módulo (protocolo https incluído, sem barra final a mais).

Sincronização muito longa ou timeout

A API pagina por lotes de 25 000 linhas. Para os sites grandes: aumente memory_limit para 512M, aumente max_execution_time e privilegie o cron (que não tem o limite de tempo do navegador).

URLs não resolvidos em entidades PrestaShop

O resolvedor trabalha sobre o link_rewrite (slug do URL amigável). Os URLs gerados por módulos de routing de terceiros podem ficar por ligar: aparecem com o tipo « other » mas continuam plenamente analisados.

Desinstalação

A desinstalação elimina as 4 tabelas SQL, os separadores de administração e todas as chaves de configuração (incluindo os tokens OAuth). Lembre-se de revogar o acesso da aplicação nas definições de segurança da sua conta Google se já não usar o módulo.