PS PrestaShop PrestaShop Intermédio

Predictive SEO: documentação completa

Ligar a Google Search Console, configurar o fornecedor de IA, compreender o motor de previsão e explorar as oportunidades sazonais detetadas.

Atualizado Versão do módulo 1.0.0

Visão geral

O DataFirefly Predictive SEO liga o seu PrestaShop à Google Search Console, aplica um motor de previsão de aprendizagem automática embutido ao histórico de pesquisa e identifica automaticamente os picos sazonais que aí vêm. Para cada oportunidade detetada, pode gerar com um clique um resumo editorial estruturado através da Mistral, da OpenAI ou da Claude.

A reter: o Predictive SEO não mede o que já aconteceu, projeta o que vai acontecer. O módulo funciona em pura antecipação: publica o conteúdo duas semanas antes do pico de pesquisa e ganha a posição antes da onda.

Pré-requisitos

  • PrestaShop 8.0+ ou PrestaShop 9.x
  • PHP 8.1 no mínimo
  • MySQL 5.7+ ou MariaDB 10.3+
  • Uma conta Google com acesso à propriedade Search Console da loja
  • Uma chave de API de um fornecedor de IA (Mistral, OpenAI ou Anthropic; Mistral por predefinição, cerca de 0,002 € por resumo)
  • No mínimo 60 a 90 dias de histórico na GSC para previsões fiáveis

Instalação

Instalação a partir do ZIP

  1. Descarregue o ZIP dfpredictiveseo.zip a partir da sua área de cliente DataFirefly.
  2. No back-office PrestaShop, vá a Módulos → Gestor de módulos.
  3. Clique em Carregar um módulo e coloque o ZIP.
  4. O módulo instala-se automaticamente, cria as 7 tabelas dfpseo_*, regista os 6 separadores em MELHORAR e gera um token de cron único.
  5. Depois de instalado, encontra o módulo no menu Melhorar → Predictive SEO.
Atualização: numa atualização futura, o carregamento de um novo ZIP substitui os ficheiros e executa automaticamente os scripts upgrade-X.Y.Z.php. Os dados e a configuração são conservados.

Esquema da base de dados

A instalação cria 7 tabelas com o prefixo dfpseo_:

  • dfpseo_keyword: palavras-chave seguidas a partir da GSC
  • dfpseo_history: histórico diário (impressões, cliques, CTR, posição)
  • dfpseo_forecast: previsões diárias com intervalos de confiança
  • dfpseo_opportunity: oportunidades sazonais detetadas
  • dfpseo_recommendation: resumos editoriais gerados pela IA
  • dfpseo_seasonality: índices sazonais (dia da semana × mês) por palavra-chave
  • dfpseo_sync_log: registo das sincronizações com a GSC

Configuração da Google Search Console

O módulo usa o protocolo OAuth2 padrão. Cria um cliente OAuth no Google Cloud, cola as credenciais nas definições e inicia o fluxo de autorização a partir do botão Ligar.

Passo 1: criar um projeto no Google Cloud

  1. Vá a console.cloud.google.com e inicie sessão com a conta Google que tem acesso à sua propriedade Search Console.
  2. Clique no seletor de projeto no canto superior esquerdo e depois em Novo projeto.
  3. Dê-lhe um nome, por exemplo DataFirefly Predictive SEO, e crie-o.

Passo 2: ativar a API Search Console

  1. No menu da esquerda, vá a APIs e Serviços → Biblioteca.
  2. Procure Search Console API e clique em Ativar.

Passo 3: configurar o ecrã de consentimento OAuth

  1. Vá a APIs e Serviços → Ecrã de consentimento OAuth.
  2. Tipo de utilizador: Externo.
  3. Preencha o nome da aplicação, o e-mail de apoio e o domínio autorizado (a sua loja).
  4. Em Âmbitos, acrescente https://www.googleapis.com/auth/webmasters.readonly (leitura da Search Console).
  5. Em modo de teste, acrescente o seu e-mail em Utilizadores de teste. Pode passar a produção mais tarde, sem alterar o módulo.

Passo 4: criar o cliente OAuth

  1. Vá a APIs e Serviços → Credenciais.
  2. Clique em Criar credenciais → ID de cliente OAuth.
  3. Tipo de aplicação: Aplicação Web.
  4. Nome: à sua escolha (por exemplo Predictive SEO Produção).
  5. URI de redirecionamento autorizado: copie o URI apresentado nas definições do módulo (Melhorar → Predictive SEO → Definições → Google Search Console → URI de redirecionamento). Formato: https://a-sua-loja.pt/module/dfpredictiveseo/settings/oauth_callback.
  6. Clique em Criar: o Google mostra o client_id e o client_secret.

Passo 5: ligar o módulo

  1. Nas definições do Predictive SEO, cole o client_id e o client_secret.
  2. Grave.
  3. Clique em Ligar à Google Search Console.
  4. É redirecionado para a página de consentimento do Google. Autorize o acesso de leitura.
  5. De volta ao back-office, o módulo guardou o refresh_token cifrado e está pronto a sincronizar.
  6. Selecione depois a propriedade Search Console a seguir na lista pendente (o módulo deteta-a automaticamente após a ligação).
Atenção: o URI de redirecionamento tem de ser idêntico ao caractere entre o Google Cloud e o módulo. Uma diferença de protocolo (http/https), de barra final ou de subdomínio provoca um erro redirect_uri_mismatch.

Configuração do fornecedor de IA

O módulo suporta 3 fornecedores de IA para gerar os resumos editoriais. Só precisa de um, e fornece a sua própria chave de API do fornecedor escolhido: a DataFirefly não cobra qualquer comissão sobre a utilização.

Mistral (predefinição, recomendado)

  • Modelo: mistral-small-latest
  • Custo indicativo: cerca de 0,002 € por resumo gerado
  • Criar a chave: console.mistral.ai → API Keys
  • Colar a chave em Definições → Fornecedor de IA → Chave API Mistral

OpenAI

  • Modelo: gpt-4o-mini
  • Custo indicativo: cerca de 0,005 € por resumo
  • Criar a chave: platform.openai.com → API keys
  • Colar a chave em Definições → Fornecedor de IA → Chave API OpenAI

Anthropic (Claude)

  • Modelo: claude-3-5-haiku-latest
  • Custo indicativo: cerca de 0,004 € por resumo
  • Criar a chave: console.anthropic.com → API Keys
  • Colar a chave em Definições → Fornecedor de IA → Chave API Anthropic

Selecione depois o fornecedor ativo na lista pendente Fornecedor de IA ativo. Se mudar de fornecedor, os resumos já gerados não são regenerados automaticamente.

Os resumos seguem o idioma das palavras-chave da sua propriedade Search Console. Numa loja portuguesa, releia os primeiros resumos gerados para confirmar que o texto sai em português europeu e não em português do Brasil, e ajuste os títulos e a meta description propostos antes de os usar.

Sincronização dos dados

Primeira sincronização

Estabelecida a ligação à GSC, faça uma primeira sincronização manual: Definições → Iniciar a sincronização. O módulo traz o histórico dos últimos 90 dias para a propriedade selecionada, até 250 000 linhas por sincronização, com as dimensões data × consulta × página. A primeira sincronização pode demorar de 30 segundos a 2 minutos, consoante o volume.

Cron diário

Para as sincronizações automáticas, configure um cron diário (recomendado: de madrugada, entre as 4h e as 6h no fuso Europe/Lisbon) que chame o endpoint protegido do módulo.

O URL exato e o token são apresentados em Definições → Cron. Formato genérico:

https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=O_SEU_TOKEN_GERADO

Exemplo de linha de crontab (cron Unix):

0 5 * * * curl -s "https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=O_SEU_TOKEN" > /dev/null 2>&1
Sugestão: o token é gerado aleatoriamente na instalação e guardado na tabela de configuração do PrestaShop (DFPSEO_CRON_TOKEN). Se o comprometer, pode regenerá-lo em Definições → Regenerar o token do cron.

Sequência de uma sincronização

Cada sincronização executa em série:

  1. Recolha na GSC dos últimos 90 dias móveis (dimensões data/consulta/página)
  2. Inserção e atualização em dfpseo_keyword e dfpseo_history
  3. Recálculo dos índices sazonais (por palavra-chave com histórico suficiente)
  4. Geração das previsões no horizonte configurado
  5. Deteção das oportunidades na janela futura
  6. Registo em dfpseo_sync_log

Painel

O painel (Melhorar → Predictive SEO → Painel) reúne os indicadores-chave:

  • 4 cartões de KPI: palavras-chave seguidas, oportunidades por vir, cliques previstos a 14 dias, última sincronização com a GSC
  • Gráfico principal: curva agregada do histórico (90 dias) e da previsão (horizonte configurado, 30 dias por predefinição), com banda de confiança de 95 %
  • Principais oportunidades: os 10 próximos picos sazonais ordenados por pontuação
  • Registo de sincronizações: as 5 últimas sincronizações com o respetivo estado

Estado da ligação

Dois emblemas no topo do painel indicam o estado das integrações: GSC ligada (verde/vermelho) e Fornecedor de IA configurado (verde/vermelho). Se algum estiver a vermelho, siga a ligação direta para as definições correspondentes.

Palavras-chave e previsões

Lista de palavras-chave

O separador Palavras-chave mostra a grelha nativa do PrestaShop com todas as consultas sincronizadas. Colunas: consulta, página de destino, impressões a 30 dias, cliques a 30 dias, CTR, posição média e última atualização. Pode filtrar, ordenar e exportar.

Vista detalhada por palavra-chave

Um clique numa palavra-chave abre a sua ficha:

  • Curva individual de histórico e previsão própria
  • Intervalo de confiança de 95 % em torno da previsão
  • Mapa de calor sazonal 12 × 7 (mês × dia da semana)
  • Índices sazonais calculados
  • Lista das oportunidades ligadas a essa palavra-chave

Mapa de calor da sazonalidade

O mapa de calor mostra os índices sazonais multiplicativos. Leitura:

  • Célula a 1,00: tráfego médio nessa combinação mês × dia
  • Célula a 1,50: tráfego 50 % acima da média (pico sazonal)
  • Célula a 0,60: tráfego 40 % abaixo da média (vale)

As células são coloridas do azul-claro (vale) ao azul-escuro e ao laranja-avermelhado (pico). Basta um olhar para identificar as semanas a explorar.

Oportunidades sazonais

Deteção automática

É detetada uma oportunidade quando, numa janela futura de 14 dias (configurável em DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS):

  • A previsão ultrapassa a linha de base da palavra-chave × 1,25 (limiar de pico)
  • E o índice sazonal da combinação mês × dia é superior a 1,10

Os picos contíguos (intervalo ≤ 2 dias) são agrupados numa única oportunidade que cobre a janela completa.

Pontuação da oportunidade

A pontuação combina três fatores:

pontuação = cliques_esperados × lift × confiança
  • cliques_esperados: soma dos cliques previstos na janela
  • lift: rácio entre pico e linha de base
  • confiança: largura do intervalo de previsão (quanto mais estreito, mais alta a pontuação)

Uma pontuação superior a 80 indica uma oportunidade de forte potencial e forte sinal sazonal. Entre 40 e 80, a oportunidade é moderada. Abaixo de 40, o sinal é demasiado fraco ou incerto para justificar uma ação prioritária.

Fluxo de trabalho de uma oportunidade

Cada oportunidade tem um estado:

  • Nova: acabada de detetar, a aguardar decisão
  • Em curso: foi gerado um resumo e o trabalho editorial está a decorrer
  • Tratada: conteúdo publicado, oportunidade aproveitada
  • Ignorada: decisão de não tratar (falso positivo, fora da estratégia)

Recomendações de IA

Gerar um resumo

A partir de qualquer oportunidade, clique em Gerar o resumo. O módulo envia um pedido ao fornecedor de IA ativo com o contexto da palavra-chave (volume, sazonalidade, posição atual, página em causa) e recebe um resumo estruturado em JSON com:

  • summary: resumo estratégico
  • meta_description: meta description SEO pronta a colar (150-160 caracteres)
  • search_intent: intenção de pesquisa dominante (informacional / transacional / navegacional / comercial)
  • outline: plano detalhado h1/h2/h3 do artigo ou da página
  • keywords_to_include: palavras-chave semânticas a incluir
  • internal_links: sugestões de ligações internas para outras páginas do site
  • rationale: justificação estratégica da recomendação

A geração demora 1 a 3 segundos, consoante o fornecedor.

Fluxo de aprovação

Cada resumo passa pelos estados:

  1. Pending: gerado, a aguardar revisão
  2. Approved: validado para redação
  3. Published: conteúdo publicado (a marcar manualmente)
  4. Rejected: recusado (resumo de má qualidade ou fora de tema)
  5. Draft: em alteração

O fluxo permite-lhe manter um registo claro do que já foi tratado.

Arquitetura técnica

Stack

  • Arquitetura PSR-4, namespace DfPredictiveSeo → src/
  • Controladores Symfony que estendem FrameworkBundleAdminController
  • Repositórios Doctrine DBAL (sem ObjectModel)
  • GSC acedida em REST direto por cURL e OAuth2 (sem google/apiclient, para se manter leve)
  • Sem dependências Composer obrigatórias na instalação (autoloader PSR-4 embutido)

Sequência de aprendizagem automática

  1. Decomposição sazonal multiplicativa: índices de dia da semana e de mês calculados por média móvel centrada de 28 dias e média truncada a 10 %
  2. Regressão OLS sobre log(impressões+1) para modelar a tendência log-linear
  3. Previsão: exp(previsão_log) × índice_sazonal_dia × índice_sazonal_mês
  4. Intervalos de 95 %: aproximação de Student sobre o erro residual da regressão, com alargamento progressivo ao longo do horizonte

Endpoint de cron

O endpoint é público mas protegido por token. Exemplo em PHP para chamada programática:

$token = 'o_seu_token_cron';
$url = 'https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = número de palavras-chave atualizadas
// $data['opportunities_detected'] = número de oportunidades novas detetadas

Variáveis de configuração

O módulo guarda 18 chaves de configuração na tabela ps_configuration:

  • DFPSEO_GSC_CLIENT_ID, DFPSEO_GSC_CLIENT_SECRET, DFPSEO_GSC_REFRESH_TOKEN (cifrado), DFPSEO_GSC_PROPERTY
  • DFPSEO_AI_PROVIDER, DFPSEO_AI_MISTRAL_KEY, DFPSEO_AI_OPENAI_KEY, DFPSEO_AI_ANTHROPIC_KEY
  • DFPSEO_FORECAST_HORIZON_DAYS (predefinição: 30)
  • DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS (predefinição: 14)
  • DFPSEO_PEAK_THRESHOLD (predefinição: 1.25)
  • DFPSEO_SEASONAL_THRESHOLD (predefinição: 1.10)
  • DFPSEO_CRON_TOKEN (gerado na instalação)
  • DFPSEO_LAST_SYNC, DFPSEO_LAST_FORECAST

Resolução de problemas

Erro redirect_uri_mismatch ao ligar à GSC

O URI de redirecionamento configurado no Google Cloud não corresponde exatamente ao esperado pelo módulo. Verifique:

  • Protocolo: https:// e não http://
  • Sem barra final: ...oauth_callback e não ...oauth_callback/
  • Subdomínio: com ou sem www. consoante a sua loja, tem de coincidir

A sincronização com a GSC não devolve palavras-chave

  • Confirme que a propriedade selecionada nas definições é mesmo a que recebe tráfego de SEO (e não uma domain property vazia)
  • Confirme que a conta Google ligada é proprietária ou utilizadora autorizada nessa propriedade
  • A propriedade tem de ter pelo menos alguns dias de histórico indexado (a Google Search Console publica os dados com 2 a 3 dias de atraso)

As previsões parecem pouco fiáveis

  • Confirme que tem pelo menos 60 a 90 dias de histórico. Abaixo disso, os índices sazonais não podem ser corretamente estimados
  • Nas palavras-chave erráticas (pouco sinal, muito ruído), a largura do intervalo de 95 % é propositadamente maior: o módulo mostra explicitamente uma confiança baixa
  • Para previsões mais precisas em horizontes longos (60 a 90 dias), espere ter acumulado 6 a 12 meses de histórico. O motor melhora com o tempo

O endpoint de cron devolve um erro 403

O token passado na query string não corresponde a DFPSEO_CRON_TOKEN. Verifique o valor exato em Definições → Cron. Em caso de dúvida, regenere o token e atualize o seu crontab.

O resumo de IA não é gerado

  • Confirme que colou uma chave de API válida para o fornecedor ativo selecionado
  • Verifique o seu saldo na consola do fornecedor (Mistral, OpenAI ou Anthropic)
  • Se o fornecedor devolver um erro de limite de pedidos, espere alguns minutos e tente de novo
  • Os resumos gerados são guardados em dfpseo_recommendation; em caso de erro, este também fica registado nessa tabela com o estado error

Perguntas frequentes

O módulo funciona sem a Google Search Console?

Não, a GSC é a fonte de dados essencial. O módulo precisa de um mínimo de 60 a 90 dias de histórico para produzir previsões fiáveis e calcular a sazonalidade. Se a sua loja acabou de ser lançada, espere ter pelo menos 2 meses de dados indexados antes de instalar o módulo.

Quanto custa um resumo de IA?

Depende do fornecedor escolhido. Com a Mistral (predefinição), conte cerca de 0,002 € por resumo. Com o GPT-4o-mini da OpenAI, cerca de 0,005 €. Com o Claude Haiku, cerca de 0,004 €. Fornece a sua própria chave de API e paga diretamente ao fornecedor: a DataFirefly não cobra qualquer comissão.

Quantas palavras-chave é que o módulo consegue seguir?

Não há limite definido no código. Uma sincronização normal traz até 250 000 linhas (data × consulta × página) por chamada, o que cobre a quase totalidade das lojas. Acima disso, aumente a memória PHP atribuída ao processo de cron.

O módulo é compatível com outros módulos de SEO?

Sim. O Predictive SEO nunca escreve nas páginas de produto nem nos metadados: limita-se a ler a GSC e a produzir recomendações. É totalmente compatível com todos os módulos de SEO existentes, DataFirefly ou de terceiros.

Os meus dados da GSC ficam guardados na DataFirefly?

Não. Todos os dados ficam no seu servidor, na sua base de dados PrestaShop. O módulo chama diretamente a API da Google com as suas credenciais OAuth e chama diretamente os fornecedores de IA com a sua chave de API. Nenhum dado passa pelos servidores da DataFirefly.

Que horizonte de previsão é o mais fiável?

O horizonte de 7 a 14 dias é muito fiável (intervalo de 95 % estreito). O de 30 a 60 dias é indicativo (intervalo mais largo). Acima de 90 dias, as previsões tornam-se pouco úteis para decisões operacionais: o módulo calcula-as, mas mostra uma confiança baixa.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte