Core Web Vitals PrestaShop: monitorização CrUX e diagnóstico por módulo (dfcoreweb)

O DataFirefly Core Web Vitals traz para o seu back-office as medições de desempenho realmente vividas pelos seus visitantes Chrome (relatório CrUX da Google), em separado para cada tipo de página: página inicial, categoria, página de produto, carrinho, página CMS e domínio inteiro. Conserva o histórico, avisa por e-mail quando uma métrica se degrada, compara a sua loja com os seus concorrentes e explica, com um diagnóstico PageSpeed Insights, que módulo, ficheiro do tema ou serviço de terceiros torna uma página lenta.

Pré-requisito: a chave de API da Google

O módulo utiliza duas APIs gratuitas da Google com a mesma chave: Chrome UX Report (medições reais) e PageSpeed Insights (separador Diagnóstico).

1. Abra a Google Cloud Console e crie um projeto, ou escolha um existente.
2. Em APIs e serviços > Biblioteca, ative a Chrome UX Report API.
3. Ainda na biblioteca, ative a PageSpeed Insights API.
4. Em APIs e serviços > Credenciais, clique em Criar credenciais > Chave de API e copie a chave (começa por AIzaSy).

Instalação e atualização

1. Abra Módulos > Gestor de módulos e clique em Carregar um módulo.
2. Carregue o ficheiro dfcoreweb.zip.
3. Clique em Configurar: chega ao painel do módulo.

A instalação cria 5 tabelas e um menu Core Web Vitals em Melhorar, com 5 páginas: Painel, Recomendações, Histórico, Diagnóstico e Configuração.

Atualização a partir da versão 1.0.0

Instale o novo ZIP por cima do antigo, sem desinstalar. A atualização reorganiza o menu, corrige as medições registadas pela 1.0.0 (as métricas em falta eram guardadas como 0), adiciona as novas tabelas e elimina os ficheiros antigos.

Configuração

Chave de API

Cole a chave e clique em Guardar e testar. O módulo consulta o CrUX para o domínio da loja e apresenta um destes resultados:

• Chave válida, o CrUX devolve dados: está tudo pronto.
• Chave válida, ainda sem tráfego Chrome suficiente para o domínio: a chave funciona, algumas páginas muito visitadas podem ainda assim devolver medições, e o Diagnóstico continua disponível.
• A Google recusou a chave de API: verifique a chave e se a Chrome UX Report API está ativada no projeto.
• O servidor não consegue contactar a Google: ver a resolução de problemas no fim da página.

Dispositivos monitorizados

• Telemóvel: ativado por predefinição, é o que a Google utiliza para avaliar a experiência de página.
• Computador: ativado por predefinição.
• Tablet: desativado por predefinição, o CrUX raramente tem dados suficientes neste segmento.

Fica sempre pelo menos um dispositivo ativo: se desmarcar todos, a opção Telemóvel é reativada.

Páginas medidas

A página inicial, o carrinho e o domínio inteiro são sempre medidos. Para os outros tipos, deixe o campo vazio para a seleção automática ou introduza IDs separados por vírgulas:

• IDs de produtos: vazio = os 3 produtos mais vendidos dos últimos 90 dias (encomendas validadas da loja) ou, na falta destes, os 3 produtos mais recentes.
• IDs de categorias: vazio = as 3 categorias com mais produtos ativos, excluindo as categorias raiz e início.
• IDs de páginas CMS: vazio = nenhuma página CMS medida.

Concorrentes

Introduza até 5 domínios, um por linha (concorrente.pt ou https://www.concorrente.com). Como as medições CrUX são públicas, o módulo mede o domínio inteiro de cada concorrente sem instalar nada do lado deles. Os concorrentes não entram nos alertas nem nas recomendações.

Sincronização automática

• Autorizar o URL de sincronização: ativa a tarefa agendada descrita mais abaixo.
• Importar o histórico semanal CrUX: obtém até 40 semanas de medições anteriores para cada página e depois atualiza-as uma vez por semana.
• Análise laboratorial automática: a tarefa agendada analisa uma página por dia com o PageSpeed Insights (telemóvel), pelo que cada página é revista cerca de uma vez por semana.
• Retenção do histórico: 365 dias por predefinição, de 30 a 3650. As medições, análises e eventos mais antigos são eliminados em cada sincronização.

Alertas de regressão

• Enviar um e-mail quando uma métrica se degradar: ativa os alertas.
• Destinatário: vazio = endereço de e-mail da loja.
• Limiar de degradação: 15 % por predefinição, de 5 a 100 %.

Em cada sincronização, o LCP, o INP, o CLS e o TTFB de cada página e dispositivo são comparados com a sua média dos 7 dias anteriores (pelo menos 3 medições). É enviado um alerta quando a subida ultrapassa o limiar e o valor já não está na zona verde da Google. Todas as regressões de uma sincronização cabem num único e-mail, e a mesma página não volta a gerar um alerta para a mesma métrica durante 7 dias. O botão Enviar um e-mail de teste verifica o endereço e a configuração de e-mail da loja.

Painel do PrestaShop

A opção Mostrar um resumo para telemóvel adiciona à página inicial do back-office um bloco com o LCP, o INP e o CLS em telemóvel por tipo de página e o respetivo estado.

A tarefa agendada

O separador Configuração apresenta o URL a chamar uma vez por dia e uma linha crontab pronta a copiar:

17 6 * * * curl -fsS "https://a-sua-loja.com/module/dfcoreweb/cron?token=O_SEU_TOKEN" > /dev/null

Num alojamento partilhado, utilize o agendador do seu painel de administração ou um serviço como o cron-job.org. Cada chamada:

1. atualiza a lista das páginas monitorizadas (produtos mais vendidos, categorias);
2. consulta o CrUX para cada página, dispositivo e concorrente;
3. envia o e-mail de alerta, se for necessário;
4. importa o histórico semanal quando chega a altura;
5. lança a análise laboratorial do dia;
6. elimina os dados mais antigos do que o período de retenção.

O URL responde em JSON com um código 200 quando tudo corre bem e 502 em caso de falha, para que o seu serviço de cron o possa avisar. Um token errado recebe um código 403. A tarefa funciona mesmo com a loja em manutenção e recusa-se a correr duas vezes em simultâneo para a mesma loja (bloqueio de 15 minutos).

O painel avisa-o se a tarefa nunca foi chamada ou se não houve nenhuma sincronização há mais de 3 dias. O botão Sincronizar agora lança uma recolha imediata, útil logo após a instalação.

O painel

Um bloco por tipo de página apresenta, para cada dispositivo, as cinco métricas no percentil 75 ao longo de 28 dias móveis, com as cores dos limiares da Google:

• LCP (apresentação do conteúdo principal): bom até 2,5 s, mau acima de 4 s.
• INP (capacidade de resposta às interações): bom até 200 ms, mau acima de 500 ms.
• CLS (estabilidade visual): bom até 0,1, mau acima de 0,25.
• FCP (primeira apresentação): bom até 1,8 s, mau acima de 3 s.
• TTFB (tempo de resposta do servidor): bom até 0,8 s, mau acima de 1,8 s.

O selo Aprovado ou Falhado segue a regra da Google: LCP, INP e CLS na zona verde (o INP é ignorado quando o CrUX não o publica, o que é frequente no carrinho). Sob cada valor, uma seta indica a evolução face a há 4 semanas: vermelha quando a métrica se degrada, verde quando melhora. Quando um tipo de página agrupa vários URLs, o bloco apresenta a média.

Mais abaixo, a Comparação com os seus concorrentes classifica o seu domínio e os dos seus concorrentes por LCP, para cada dispositivo. A tabela URLs monitorizados detalha cada página com as suas medições, a sua última pontuação PageSpeed (coluna Laboratório) e dois atalhos: o histórico e o diagnóstico da página.

Recomendações

Cada métrica fora da zona verde gera uma recomendação. As recomendações com a mesma causa são agrupadas num único cartão, que lista as páginas afetadas com o respetivo valor (por exemplo, o TTFB na página inicial, nas categorias e nas páginas de produto). Cada cartão indica:

• a gravidade: Crítico (zona vermelha), A corrigir (zona laranja) ou Dica;
• a causa provável neste tipo de página PrestaShop e os passos de correção;
• uma ordem de grandeza do impacto, retirada de estudos públicos e apresentada como estimativa;
• ligações para os ecrãs em causa (Desempenho, Definições de imagem, Posições dos módulos, Regras do carrinho) e para o Diagnóstico.

Ignorar durante 30 dias oculta o cartão para todas as suas páginas. O cartão volta a aparecer se uma nova página for afetada, e uma ligação no topo da página mostra as recomendações ignoradas para as voltar a apresentar.

Histórico

Escolha o tipo de página, o URL (ou a média de todos os URLs desse tipo), o dispositivo e o período (30, 90, 180 ou 365 dias). São apresentadas seis curvas: LCP, INP, CLS, TTFB, FCP e a percentagem de URLs aprovados na avaliação, com os limiares da Google a tracejado.

Antes da primeira sincronização, cada ponto corresponde a uma semana importada do histórico CrUX; depois, há um ponto por sincronização. Cada ponto abrange os 28 dias anteriores: uma alteração demora cerca de 4 semanas a refletir-se por completo.

Eventos

As instalações e desinstalações de módulos são registadas automaticamente e aparecem a tracejado nas curvas. Adicione os seus próprios marcadores com uma data e uma descrição (atualização do tema, mudança de fornecedor de alojamento, campanha) para relacionar uma variação com a sua causa. Ao passar o cursor sobre um ponto, vê os eventos próximos.

O botão Exportar CSV transfere a seleção apresentada, com a origem de cada ponto (semanal ou diário).

Diagnóstico de uma página

Escolha uma página monitorizada e o dispositivo (Telemóvel ou Computador) e clique em Iniciar a análise. A Google carrega a página a partir dos seus servidores e o resultado chega em 20 a 60 segundos. Fica guardado: mudar de página ou de dispositivo apresenta a última análise sem lançar uma nova.

Pontuação e captura

A pontuação de desempenho (em 100), os valores de LCP, TBT, CLS, FCP, Speed Index e TTFB, o peso total, o número de pedidos e a captura do que a Google apresentou.

Elemento LCP

O elemento que determina o LCP (imagem, banner, título) com o seu código HTML, e a repartição do seu tempo em quatro etapas: resposta do servidor, espera antes da transferência, transferência do recurso e atraso de apresentação. Um conselho corresponde à etapa mais longa, por exemplo pré-carregar a imagem quando é descoberta tarde, ou retirar loading="lazy" quando a imagem LCP é carregada em diferido.

O que pesa na página

Cada ficheiro carregado é atribuído à sua origem de acordo com o caminho:

• Módulo: ficheiros em /modules/nome_do_modulo/, apresentados com o nome do módulo;
• Tema: ficheiros em /themes/nome/;
• Loja: ficheiros do núcleo do PrestaShop, imagens da loja e a página HTML com os scripts escritos diretamente nela;
• Serviço de terceiros: qualquer outro domínio, identificado pela Google quando o reconhece (Google Tag Manager, Facebook, ferramentas de chat…).

Para cada origem: tempo de CPU (execução do JavaScript durante o carregamento, a principal causa de um INP elevado), peso de JS, CSS e outros ficheiros, JavaScript não utilizado e número de pedidos. A tabela está ordenada por tempo de CPU.

Ficheiros bloqueantes e problemas detetados

A lista dos ficheiros que bloqueiam a apresentação, cada um com o seu módulo ou a sua origem, e os problemas detetados pela Google (cache, formato das imagens, JavaScript não utilizado…), ordenados pelo ganho estimado, com uma pista PrestaShop para cada um. Os títulos da Google aparecem no idioma do back-office.

Análises anteriores

A tabela das últimas análises da página (pontuação, LCP, TBT, CLS, peso, ou o erro ocorrido) permite verificar o efeito de uma correção.

Análise automática

Com a opção Análise laboratorial automática, a tarefa agendada analisa todos os dias a página cuja última análise em telemóvel é a mais antiga, se tiver mais de 7 dias. Para uma loja sem medições CrUX por página, é a única medição que evolui ao longo do tempo.

O estado «Tráfego Chrome insuficiente»

O CrUX só publica uma medição se um número suficiente de visitantes Chrome tiver carregado o URL ao longo de 28 dias. Caso contrário, o módulo regista este estado sem erro e a sincronização continua. Apoie-se então no domínio inteiro, que atinge o limiar com mais facilidade, e no separador Diagnóstico para as páginas em causa.

Privacidade

Só os URLs públicos monitorizados, e os domínios concorrentes que introduzir, são enviados à Google. Nenhum dado de cliente sai da loja. Todas as medições, análises e eventos ficam na sua base de dados PrestaShop; cada análise conserva um resumo e a captura da página (cerca de 50 KB) durante o mesmo período de retenção. O Chart.js está incluído no módulo: nenhum CDN, nenhuma telemetria.

Resolução de problemas

• «A Google recusou a chave de API»: chave mal copiada, Chrome UX Report API não ativada no projeto, ou restrição por referenciador HTTP na chave.
• «A API PageSpeed Insights não está ativada» (separador Diagnóstico): ative a PageSpeed Insights API na biblioteca do mesmo projeto Google Cloud.
• «O servidor da loja não consegue contactar os servidores da Google»: o fornecedor de alojamento bloqueia as ligações de saída. Peça-lhe que autorize as ligações HTTPS de saída para googleapis.com. A sincronização para ao fim de duas falhas em vez de ficar à espera em cada página.
• «Quota excedida»: a sincronização será retomada na próxima execução da tarefa. Para o PageSpeed, tente novamente um minuto depois.
• «Já está em curso uma sincronização»: já está a decorrer uma sincronização para esta loja; tente novamente dentro de alguns minutos.
• O URL de cron responde 403: o token já não é válido (novo token ou atualização a partir da 1.0.0). Volte a copiar o URL do separador Configuração.
• O e-mail de teste não chega: verifique o endereço e Parâmetros avançados > E-mail.
• O Diagnóstico não detalha os módulos: desative a CCC durante uma análise (ver acima).
• O menu não aparece: limpe a cache em Parâmetros avançados > Desempenho e verifique as permissões do perfil de funcionário nos separadores do módulo.

Desinstalação

A desinstalação elimina as 5 tabelas do módulo, a sua configuração e os seus separadores, após confirmação. O histórico perde-se definitivamente: exporte-o em CSV a partir do separador Histórico se o quiser conservar.