# WebDig.DEV Analytics

Versão 1.0.0. Desenvolvido pela [WebDig](https://webdig.dev).

Liga o WordPress ao teu servidor Umami. O painel principal apresenta um gráfico de visitas por hora nas últimas 24 horas, visitantes, visitas, páginas vistas, duração média e taxa de rejeição.

Os separadores mostram páginas, navegadores, idiomas, sistemas operativos, dispositivos e países. O link de partilha configurável abre o relatório completo no Umami numa nova janela.

## Requisitos

- WordPress 6.4 ou posterior.
- PHP 8.0 ou posterior, com OpenSSL para guardar a chave cifrada.
- Umami alojado num servidor próprio, versão 3.2 ou posterior, acessível por HTTPS.
- Chave API ou token Bearer válido para consultar os relatórios.

## Instalação

1. Instala e ativa o ZIP em Plugins → Adicionar plugin → Carregar plugin.
2. Cria um site no Umami e copia o Website ID.
3. Abre WebDig.DEV Analytics no menu WordPress.
4. Introduz o URL base do servidor, o Website ID e a chave API. Ativa a recolha.
5. Preenche o link de partilha do Umami, se quiseres abrir o relatório completo a partir do widget.
6. Remove outros códigos ou plugins Umami e limpa o cache do site/CDN.
7. Abre Painel → Início para consultar o widget de estatísticas. Se estiver oculto, assinala-o nas Opções do ecrã.
8. Testa a recolha numa janela privada. Os administradores são excluídos da recolha por defeito.

A ativação do plugin, a recolha e a visibilidade do widget são independentes. Ativa o plugin na página Plugins e depois ativa a recolha nas configurações para começar a registar visitas. Mostrar ou ocultar o widget não inicia nem interrompe a recolha. As estatísticas aparecem na administração do WordPress e no Umami, não nas páginas públicas do site. A chave API é necessária para os relatórios no painel, mas não para recolher visitas.

Usa uma conta Umami com acesso apenas ao site em questão. Não instales a chave global de administrador nos sites dos clientes.

## Recolha

- Visualizações de páginas e cliques em botões, links, contactos e downloads.
- Scroll opcional a 25%, 50%, 75% e 90%.
- Tentativas de envio de formulários e confirmação de sucesso no Contact Form 7.
- Eventos de produtos, carrinho, checkout e confirmação de encomendas pagas no WooCommerce, com compatibilidade HPOS.
- Desempenho real e Core Web Vitals: LCP, INP, CLS, FCP e TTFB. Consulta os resultados na secção Performance do Umami.

**Visitantes** são estimativas anónimas de visitantes únicos. **Visitas** contam sessões de navegação; um visitante pode gerar várias visitas. Não representam uma contagem exata de pessoas.

O painel aparece por defeito para administradores e, se autorizado nas configurações, gestores de loja. Pode ser ocultado nas Opções do ecrã do painel WordPress. As restantes funções não ganham acesso aos dados.

## Traduções

O código original e o readme principal estão em inglês. A interface segue o idioma WordPress do utilizador. A tradução para português de Portugal (`pt_PT`) está incluída para PHP e JavaScript.

A pasta `languages` contém o modelo `.pot`, os ficheiros `.po` e `.mo` e os catálogos JavaScript JSON. Estes ficheiros permitem criar outras traduções com ferramentas compatíveis com WordPress.

## Segurança e privacidade

A chave API fica cifrada no servidor WordPress e não é enviada ao navegador. O campo permanece bloqueado até apagares a chave. Se a definires através de `WEBDIG_ANALYTICS_API_TOKEN` no `wp-config.php`, altera-a nesse ficheiro. Mudanças dos salts do WordPress exigem reintroduzir a chave guardada.

Os dados seguem para o servidor Umami que configurares. Não são enviados dados ou credenciais para a WebDig. O tracker utiliza o IP do visitante no processamento e na estimativa geográfica, de acordo com a configuração do Umami.

A recolha automática não inclui valores dos formulários nem nomes, emails ou moradas dos clientes. Os URLs excluem parâmetros e fragmentos, incluindo chaves de encomenda; por isso, a atribuição UTM através do URL também fica excluída. Os dados de eventos personalizados são da responsabilidade de quem os configura.

A deduplicação das compras guarda um marcador em localStorage. O plugin não inclui um banner nem espera por consentimento. As definições do plugin não determinam as obrigações legais do site.

## Limitações da medição de compras

As compras são registadas no navegador quando a encomenda está paga e o comprador regressa à confirmação com uma chave válida. Pagamentos posteriores por transferência ou Multibanco não são enviados por um webhook nesta versão.

A deduplicação funciona no mesmo navegador. Outros dispositivos ou a limpeza do armazenamento podem causar repetições. Reembolsos não alteram a compra original no Umami. As receitas analíticas não substituem a contabilidade.

São suportados os eventos AJAX clássicos e os eventos WooCommerce Blocks. Os formulários de produto sem AJAX geram `add_to_cart_attempt`, que significa tentativa de adição. Extensões de carrinho personalizadas podem precisar de integração adicional.

## Atualização e remoção

As atualizações e a desativação mantêm as configurações. Ao desinstalar, são apagadas as configurações e os caches locais deste site. Os dados no servidor Umami não são apagados. Em multisite, configura cada site separadamente; não está incluído provisionamento de toda a rede.

## Licença

GPL-2.0-or-later. Projeto independente, não afiliado ao Umami.
