# WebDig.DEV Analytics

Versão 1.2.0. Desenvolvido por João Costa - [WebDig.DEV](https://webdig.dev).

Liga o WordPress ao teu servidor Umami. A página de relatórios e o widget do painel mostram visitas, visitantes, páginas vistas, duração média e taxa de rejeição, para as últimas 24 horas, 7 dias, 30 dias ou um intervalo personalizado (até 366 dias), com comparação com o período anterior.

Os separadores mostram páginas, origens de tráfego, eventos, desempenho (Core Web Vitals), receita WooCommerce, 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 a partir dos navegadores. Os separadores Desempenho e Receita foram verificados com o Umami 3.4.
- 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 > Configurações no menu WordPress.
4. Introduz o URL base do servidor, o Website ID e a chave API. Ativa a recolha.
5. Confirma os domínios registados (preenchidos com o domínio deste site) e escolhe o que queres recolher. Numa loja WooCommerce, escolhe o registo de compras pelo servidor.
6. Preenche o link de partilha do Umami, se quiseres abrir o relatório completo a partir do widget.
7. Remove outros códigos ou plugins Umami e limpa o cache do site/CDN.
8. Abre WebDig.DEV > Analytics para os relatórios ou Painel → Início para o widget. Se estiver oculto, assinala-o nas Opções do ecrã.
9. 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. 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 externos, contactos e downloads, com até 50 caracteres do texto do botão ou link. Os cliques em links de email e telefone não incluem o texto. Os cliques em links internos são opcionais.
- 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 compras no WooCommerce, com compatibilidade HPOS.
- Desempenho real e Core Web Vitals: LCP, INP, CLS, FCP e TTFB, visíveis no separador Desempenho com a classificação Bom / A melhorar / Fraco e as páginas mais lentas.

Para excluir um elemento da recolha de cliques, acrescenta-lhe o atributo `data-webdig-ignore`.

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

## Sites de staging

Só os domínios indicados em "Domínios registados" enviam dados e, por defeito, só em ambientes de produção (`WP_ENVIRONMENT_TYPE`). Uma cópia da base de dados mantém a lista de domínios de produção, por isso um clone de staging não envia dados. Ao atualizar para a 1.2.0, a lista é preenchida com o domínio do site na primeira visita de um administrador à administração.

## Campanhas e URLs

Os URLs registados mantêm apenas os parâmetros da lista "Parâmetros de URL a manter": por defeito `utm_*`, `gclid`, `fbclid` e `msclkid`. Todos os outros parâmetros e fragmentos são removidos, e as chaves de encomenda (`key`) nunca são mantidas. Os referrers externos ficam reduzidos à origem.

## Consentimento

Ativa "Aguardar consentimento antes de carregar o tracker". No modo automático, o plugin segue a categoria "statistics" da WP Consent API, do Complianz e do Cookiebot e a categoria "analytics" do CookieYes. Outros gestores podem chamar `window.WebDigAnalytics.setConsent(true)` após autorização e `window.WebDigAnalytics.setConsent(false)` na revogação. Antes da autorização, o tracker não é carregado. Voltar a dar consentimento não cria uma página vista duplicada. Opcionalmente, o plugin respeita os sinais Do Not Track e Global Privacy Control.

O plugin não inclui banner. As definições do plugin não determinam as obrigações legais do site.

## Compras WooCommerce

**Navegador** (por defeito): a compra é registada quando o comprador chega à confirmação com uma chave válida e a encomenda está paga. A deduplicação funciona no mesmo navegador, através de um marcador em localStorage.

**Servidor** (recomendado): no checkout, o plugin regista se a encomenda pode ser contada, de acordo com o consentimento, os sinais de privacidade e as exclusões por perfil. Quando o WooCommerce marca a encomenda como paga, a compra é enviada uma única vez pelo servidor através do Action Scheduler, com até três tentativas; uma falha final fica registada numa nota da encomenda. Assim ficam incluídos os pagamentos posteriores por Multibanco ou transferência e as compras de visitantes com ad-blockers. As encomendas criadas na administração ou pela REST API não são enviadas. O IP e o navegador do cliente guardados pelo WooCommerce são enviados ao teu servidor Umami para associar a compra à sessão do visitante. Quando o consentimento é obrigatório, o tracker guarda-o no cookie próprio `wda_consent` (ou usa a WP Consent API) para que o servidor o respeite.

Em ambos os modos, reembolsos não alteram a compra original no Umami e as receitas analíticas não substituem a contabilidade. Os formulários de produto sem AJAX geram `add_to_cart_attempt`.

## Servidor Umami e ad-blockers

- **Umami no mesmo servidor ou em Docker:** o URL público não aceita endereços privados. Preenche o "URL interno da API" (por exemplo `http://127.0.0.1:3000` ou `http://umami:3000`) para os pedidos do WordPress; os visitantes continuam a usar o URL público em HTTPS. O teste de ligação mostra o erro técnico quando um pedido falha.
- **Ad-blockers:** configura `TRACKER_SCRIPT_NAME` no servidor Umami e indica o mesmo nome em "Nome do script do tracker". O registo de compras pelo servidor nunca é afetado por ad-blockers.

## Acesso aos relatórios

Os administradores têm sempre acesso. Podes selecionar perfis e utilizadores adicionais para consultar relatórios, sem acesso às configurações. Clientes e subscritores não aparecem na lista de utilizadores: concede acesso por perfil. Se outro plugin WebDig.DEV tiver criado o menu partilhado só para administradores, os leitores recebem uma entrada própria "Analytics" no menu.

## 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. A recolha automática não inclui valores dos formulários nem nomes, emails ou moradas dos clientes.

## Traduções

A interface segue o idioma WordPress do utilizador. Estão incluídas traduções PHP e JavaScript para pt_PT, es_ES, fr_FR, de_DE e it_IT. A pasta `languages` contém o modelo `.pot`, os ficheiros `.po` e `.mo` e os catálogos JavaScript JSON.

## 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, os envios de compras agendados e os caches locais deste site. Os dados no servidor Umami não são apagados. Em multisite, configura cada site separadamente.

## Desenvolvimento

As ferramentas de desenvolvimento não fazem parte do ZIP distribuído:

- `composer install`, depois `composer lint` (WordPress Coding Standards) e `composer test` (PHPUnit).
- `npm test` corre os testes do tracker no Chromium com Playwright; `npm run format` aplica o Prettier.
- `python3 bin/i18n.py` regenera os ficheiros `.pot`, `.po`, `.mo` e JSON.
- `bash bin/build.sh` cria o ZIP de distribuição.

## Novidades da versão 1.2.0

- Registo de compras WooCommerce pelo servidor (Action Scheduler), incluindo Multibanco e transferências, com consentimento recolhido no checkout.
- Novos separadores Desempenho (Core Web Vitals), Receita, Eventos e Origens.
- Proteção contra sites de staging: lista de domínios registados e opção só produção.
- Parâmetros de campanha (`utm_*`) e IDs de clique mantidos nos URLs; chaves de encomenda sempre removidas.
- Deteção automática de consentimento (WP Consent API, Complianz, CookieYes, Cookiebot) e suporte opcional a Do Not Track / Global Privacy Control.
- Nome do script do tracker configurável, URL interno da API, preconnect e detalhe técnico no teste de ligação.
- Eventos de clique com o texto do elemento; cliques em links internos opcionais (os sites existentes mantêm o comportamento anterior).
- Gráfico com tooltip ao passar o rato ou com o teclado; datas formatadas no idioma do utilizador.
- Correções: lista de utilizadores leve em lojas grandes; leitores sem acesso indevido ao hub de outro plugin; sem páginas vistas duplicadas ao voltar a dar consentimento; links malformados já não interrompem a recolha de cliques; fusos horários em formato de desvio UTC codificados corretamente; tabelas com a etiqueta correta (visitantes).
- Menos um pedido à API por atualização, usando a comparação devolvida pelo Umami 3.
- Código organizado em classes segundo os WordPress Coding Standards, com testes PHPUnit e de browser.

## Licença

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