Umami Analytics
Plugin Umami não oficial, sem afiliação com o Umami: tráfego, páginas mais vistas, referenciadores e visualizações por entrada na administração do EmDash.
Extensão
Umami Analytics
Plugin Umami não oficial, sem afiliação com o Umami: tráfego, páginas mais vistas, referenciadores e visualizações por entrada na administração do EmDash.
Descrição
Um plugin não oficial. Não é afiliado, aprovado nem suportado pelo Umami.
Mostra os seus números do Umami dentro da administração do EmDash: o tráfego do site no painel e as visualizações de página junto às entradas que as geraram. Para o Umami Cloud e para um Umami autoalojado a partir da versão 3.4.0.
- Cartão de tráfego do Umami. No painel: visitas, visualizações de página e envolvimento dos últimos sete dias face à semana anterior, e as cinco páginas mais vistas com as respetivas entradas.
- Página Umami Analytics. Um gráfico diário de 7, 30 ou 90 dias, taxa de rejeição e duração da visita, principais entradas, referenciadores, países, visualizações de página segundo os dados de eventos que o seu site anexa (por categoria, para começar) e uma verificação da configuração que indica a solução para cada problema que encontra.
- Página por entrada. Cada entrada publicada com as suas visualizações de página a 7 e 30 dias, ordenáveis, para uma coleção ou para todas, com as traduções combinadas se quiser.
- Painel do Umami no editor. As visualizações de página a 7 e 30 dias de cada entrada junto ao editor, e até onde chegam os leitores quando o seu site envia um evento de leitura.
- Ferramentas MCP. Quatro ferramentas só de leitura que respondem a partir dos números guardados.
O plugin apenas lê. Nunca altera nada no Umami nem no seu conteúdo. Os dados de demonstração permitem experimentá-lo sem um site no Umami.
Foi testado com um Umami 3.4.0 autoalojado. A ligação ao Umami Cloud segue a API publicada pelo Umami e ainda não foi testada com uma conta Cloud.
Baseado no plugin de analítica do EmDash de Eisbachcode, sob licença MIT.
Instalação
Precisa de: EmDash 1.0.1 ou posterior com um executor de sandbox para plugins; um site no Umami com o script de acompanhamento do Umami já instalado no seu site; um Umami autoalojado 3.4.0 ou posterior (a primeira versão autoalojada com chaves de API) ou o Umami Cloud; e EMDASH_ENCRYPTION_KEY definida no site para que a chave de API possa ser guardada cifrada (npx emdash secrets generate cria uma).
- Instale o plugin a partir do registo e reveja as suas permissões: ler conteúdo, ler o esquema e fazer pedidos de rede a qualquer anfitrião público. O plugin só pede o URL da API do Umami indicado nas suas definições.
- No Umami, crie um utilizador com a função View only. Adicione-o à equipa que possui o seu site, com a função de equipa View only. Se o site for seu e não de uma equipa, mova-o primeiro para uma equipa.
- Inicie sessão no Umami com esse utilizador e crie uma chave em Settings > API keys.
- No EmDash, abra Plugins e depois as definições deste plugin. Cole a chave em Umami API key.
- Para um Umami autoalojado, defina Umami API URL como
https://your-host/api. O valor predefinido é o endereço do Umami Cloud. - Introduza o ID do site do Umami que consta nas definições do site no Umami. Se o deixar vazio, o cartão do painel lista os sites que a chave consegue ver, para que possa copiar um. Guarde.
- Abra Plugins > Umami Analytics e selecione Check setup. Percorre tudo de que os números dependem e dá uma frase por cada problema.
As primeiras sincronizações leem para trás até Keep daily rows for (90 dias por predefinição), começando pelas mais recentes. No Node, isto demora cerca de duas horas para um site com 100 entradas.
Cada coleção precisa de um padrão de URL (em Tipos de conteúdo); caso contrário, as páginas não podem ser associadas a entradas. No Cloudflare Workers, a sincronização precisa do Cron Trigger do guia de implementação do EmDash.
Um Umami autoalojado tem de estar num nome de anfitrião público: o EmDash recusa endereços privados, pelo que localhost, um endereço de rede local ou um nome acessível apenas por VPN não funcionarão.
Para usar as ferramentas MCP, ative o acesso Agent do plugin em Plugins. Volte a ativá-lo após uma atualização que altere uma ferramenta.
Perguntas frequentes
Porque é que tudo mostra zero? A maioria dos erros de configuração dá zeros sem qualquer erro. Abra Plugins > Umami Analytics e selecione Check setup: indica a solução para cada problema que encontra.
Porque é que os meus números diferem dos do painel do Umami?
Os dias seguem a definição Time zone: use o fuso horário do site no Umami, ou os valores diários diferem perto da meia-noite. As páginas em /_emdash são ignoradas e os totais contam apenas os nomes de anfitrião em Hostnames to count (o URL do seu site e a sua forma com www, salvo alteração).
Funciona com o Umami Cloud? Segue a API publicada pelo Umami, mas ainda não foi testado com uma conta Cloud. Comunique o que encontrar nas issues do repositório.
O meu Umami está atrás de um proxy com início de sessão. Deixe passar sem ele os oito endpoints da API do Umami que o plugin usa. O README lista-os, e o Umami verifica a chave de API em cada um.
Quantos pedidos faz? Uma sincronização faz no máximo sete pedidos ao Umami. Abrir a página Umami Analytics faz cinco.
Posso experimentá-lo sem o Umami? Sim. Defina Data source como Demo data e selecione Refresh no cartão do painel. Gera 90 dias de tráfego inventado sobre as suas entradas reais. Mudar a origem de dados apaga todos os números guardados, pelo que os números de demonstração nunca se misturam com os reais.
Quem pode ver os números? Editores e administradores veem o cartão do painel, as duas páginas do Umami e as ferramentas MCP. Os autores veem o painel do editor das suas próprias entradas.
De onde vêm as tabelas por categoria?
Dos dados de eventos que o seu site anexa às suas visualizações de página através do hook data-before-send do rastreador do Umami. Indique até três propriedades em Views by event data. Um site que não envie nenhuma não vê tabelas.
Como funciona a profundidade de leitura?
O seu site envia um evento personalizado quando um leitor atinge cada profundidade de uma entrada, por exemplo post_read com post e depth. Preencha as quatro definições de Read-through em conformidade. Por predefinição estão vazias, o que desativa a funcionalidade.
Que idiomas fala? Inglês e alemão, de acordo com o idioma de administração de cada utilizador.
Segurança
Comunique um problema de segurança em privado através do formulário de avisos do repositório: https://github.com/shanelord01/emdash-umami-analytics/security/advisories/new
O que a chave de API do Umami pode fazer
Uma chave de API do Umami não tem permissões próprias. Pode fazer tudo o que o utilizador que a criou pode fazer. Uma chave criada com um utilizador administrador poderia alterar ou eliminar todos os sites do seu Umami, por isso crie-a com um utilizador com a função View only, adicionado à equipa do site com a função de equipa View only. Uma chave criada assim pode ler os sites dessa equipa e não alterar nada. O próprio plugin só envia pedidos GET.
Acesso à rede
O plugin pede network:request:unrestricted, porque um Umami autoalojado está num anfitrião que escreve nas definições e que nenhuma lista fixa de anfitriões poderia nomear. Só pede o URL da API do Umami indicado nas suas definições (https://api.umami.is/v1, salvo alteração), com a chave como token Bearer. Os dados de demonstração não fazem qualquer pedido. O EmDash recusa endereços privados para todos os plugins.
O que é enviado e o que é guardado
- O Umami recebe a chave de API, o ID do site e os nomes de anfitrião a contar. Nada do seu conteúdo sai do site.
- A chave é guardada como definição cifrada (AES-GCM com
EMDASH_ENCRYPTION_KEY). Sem essa chave, o EmDash recusa guardá-la em vez de a armazenar em texto simples. O plugin nunca a escreve nos seus registos. - A base de dados do site guarda as visualizações de página e visitas por dia e caminho, os totais do site e o envolvimento por dia, a associação de cada caminho à sua entrada com as contagens de visualizações e a profundidade de leitura dessa entrada, e o estado da sincronização com as páginas, referenciadores e países principais da última semana. As linhas diárias anteriores a Keep daily rows for são eliminadas.
Quem pode fazer o quê
O cartão do painel, as páginas Analytics e Per entry e as ferramentas MCP exigem a função de editor. O painel do editor exige a função de autor e mostra apenas as entradas que o utilizador pode editar. Alterar as definições exige a função de administrador.
Registo de alterações
0.1.4
- No EmDash 1.2 e posteriores, as páginas ficam numa única pasta do Umami na barra lateral (Analytics, Per entry). Os seus endereços não mudam; as versões anteriores do EmDash listam-nas uma a uma.
- Sem novas permissões e sem alterações às ferramentas MCP.
0.1.3, 9 de outubro de 2026
- Os dias seguem o seu fuso horário. Antes eram dias UTC, pelo que uma visualização de página antes das 10 h aproximadamente em Sydney contava no dia anterior. A nova definição Time zone começa em Australia/Sydney. Defina o fuso do site no Umami.
- Na atualização, os números guardados são apagados uma vez e relidos do Umami, começando pelos mais recentes. Os gráficos e as visualizações por entrada voltam a encher-se durante a recuperação: cerca de duas horas para 90 dias e 100 entradas no Node, ao ritmo do Cron Trigger no Cloudflare Workers. Alterar a definição mais tarde produz o mesmo efeito.
- Com o nome do Umami para não serem confundidos com os de outro plugin: as páginas Umami Analytics e Umami per entry (mesmos endereços), o cartão de tráfego do Umami e o painel do Umami no editor.
- A página do registo tem separadores, incluindo este registo de alterações, e um banner.
- Correções da administração: deixou de aparecer o falso «nenhuma página associada», as páginas principais do painel cobrem os seus 7 dias, o gráfico diário indica o nome da sua série e o painel do editor indica o dia em que começa o seu histórico guardado.
- Sem novas permissões. As ferramentas MCP passam a descrever os seus dias no seu fuso horário, pelo que o EmDash desativa o acesso Agent após a atualização. Volte a ativá-lo em Plugins.
0.1.2, 1 de outubro de 2026
- Envolvimento junto aos totais: taxa de rejeição, visita média e páginas por visita face ao período anterior, e um novo campo
engagementemsite_totals. - Profundidade de leitura por entrada (quatro definições, desativada por predefinição) e dois novos endpoints do Umami usados apenas com ela ativada. Recuperação mais rápida após a instalação.
- Volte a ativar o acesso Agent em Plugins após a atualização.
Histórico completo: CHANGELOG.md.