Instalação do Tracker
Adicione o script abaixo no <head> ou antes do </body> de todas as páginas que deseja monitorar.
Não é necessário nenhuma configuração adicional. O script detecta automaticamente a URL atual, dispositivo, idioma, fuso horário e parâmetros UTM.
Sites SPA (React, Vue, Next.js...)
O tracker já suporta navegação client-side automaticamente. Ele intercepta as mudanças de rota via history.pushState e registra cada página visitada como um evento spa_navigate.
Verificando a instalação
Após instalar, acesse o painel e veja a seção Eventos Recentes. Em alguns segundos você deve ver sua visita aparecer.
Métricas Explicadas
Pageviews
Total de páginas carregadas, incluindo navegações SPA. Conta múltiplas visitas do mesmo usuário.
Visitantes Únicos
Visitantes distintos por dia. Calculado com hash de IP + User-Agent + data. Sem cookies.
Sessões
Número de sessões únicas. Uma sessão é uma sequência contínua de interações do mesmo usuário em uma aba.
Tempo Médio na Página
Média de segundos gastos em cada página antes de sair. Calculado apenas para eventos leave.
Scroll Médio
Percentual médio da página que os visitantes rolaram. 100% = leu até o final.
Leitura Profunda
% de sessões em que o usuário scrollou mais de 75% da página. Indica engajamento real com o conteúdo.
Tipos de eventos
pageview— Carregamento inicial da páginaspa_navigate— Navegação interna em SPA (sem reload)leave— Saída da página (envia dados de engajamento: tempo, scroll, cliques)
Usando o Painel
Filtros de período
Use os botões 7d 30d 90d no canto superior direito para ajustar o período analisado. No modo 90 dias, o gráfico de tráfego agrupa os dados por semana.
Seleção de domínio
O selector de domínio no header filtra todos os dados para um site específico. Por padrão, exibe dados de todos os domínios monitorados. Os domínios são populados automaticamente a partir dos dados existentes.
Seções do painel
- KPIs — Métricas principais com comparação ao período anterior (badge verde/vermelho)
- Tráfego ao longo do tempo — Gráfico de área com pageviews e visitantes únicos
- Dispositivos — Distribuição entre desktop, mobile e tablet
- Top páginas — Páginas mais acessadas com tempo médio e scroll
- Origens de tráfego — Referrer dos visitantes (Google, Instagram, Direto, etc.)
- Localização — Países e cidades via GeoIP (ip-api.com)
- Campanhas UTM — Dados de source, medium e campaign
- Navegadores / OS — Distribuição por browser e sistema operacional
- Eventos recentes — Feed ao vivo dos últimos eventos (atualiza a cada 30s)
- Links Compartilhados — Gerenciamento de acesso para clientes
Links Compartilhados
Crie links de acesso read-only para dar aos seus clientes uma visão do analytics do domínio deles, sem exposição dos outros domínios ou controles administrativos.
Como criar um link
- No painel, role até a seção Links Compartilhados
- Clique em + Novo link
- Selecione o domínio, adicione um label (ex: "João Silva") e defina a validade
- Clique em Criar link e copie a URL gerada
- Envie o link ao cliente — ele abre uma versão read-only do painel filtrada para aquele domínio
Opções de validade
- Sem expiração — link permanente (pode ser revogado manualmente)
- 7 / 30 / 90 dias — o link expira automaticamente após o prazo
Revogar um link
Na lista de links, clique em Revogar. O link perde o acesso imediatamente. Links revogados não são deletados, apenas desativados.
O que o cliente vê
O link abre a página share.html com o dashboard completo, mas com o domínio fixado e sem acesso a: outros domínios, seção de links compartilhados, botão de logout, diagnósticos.
Parâmetros UTM
Use UTM params nas URLs de campanhas para rastrear a origem do tráfego com precisão. O tracker captura e preserva estes parâmetros automaticamente, mesmo em navegações SPA.
Estrutura básica
Parâmetros suportados
utm_source
Origem do tráfego. Ex: google, instagram, newsletter
utm_medium
Canal de marketing. Ex: cpc, social, email
utm_campaign
Nome da campanha. Ex: black-friday-2025
utm_term / utm_content
Palavras-chave pagas e variação do anúncio (uso avançado).
Exemplo — Campanha Instagram
Configuração Inicial
1. Criar o banco de dados
2. Variáveis de ambiente
Configure estas variáveis no seu servidor (via .env, php-fpm.conf ou painel de hospedagem):
3. Configurar o bot do Telegram
- Abra o Telegram e converse com @BotFather
- Use
/newbotpara criar um bot (ex:@magicloginst_bot) - Copie o token gerado e defina como
ST_TELEGRAM_BOT_TOKEN - O usuário admin precisa iniciar conversa com o bot (enviar qualquer mensagem)
- Para descobrir seu Chat ID, converse com @userinfobot
4. Adicionar o primeiro usuário admin
5. Primeiro login
- Acesse
https://apps2.stivetec.com/st-analytics/login.html - Digite o e-mail cadastrado
- Verifique o Telegram — o bot enviará o link de acesso
- Clique no link (válido por 15 minutos)
- A sessão dura 30 dias
FAQ
O tracker filtra bots?
Sim. O tracker.php possui uma lista de padrões de User-Agent que descarta automaticamente Googlebot, Lighthouse, crawlers SEO (Ahrefs, SEMrush), ferramentas HTTP (curl, wget) e navegadores headless.
Funciona sem cookies?
Sim. O visitante único é identificado com um hash diário de IP + User-Agent (sem armazenamento no navegador do visitante). O sistema de autenticação usa cookies apenas para o administrador do painel.
Não recebi o link no Telegram.
Verifique se: (1) o e-mail está cadastrado no sistema (php migrate.php list-users), (2) o telegram_chat_id está correto, (3) você iniciou conversa com o bot pelo Telegram, (4) a variável ST_TELEGRAM_BOT_TOKEN está configurada corretamente.
Os dados de geolocalização são precisos?
O GeoIP usa o serviço gratuito ip-api.com (até 1.000 req/min). A precisão é boa para país/cidade, mas pode variar para IPs de VPN ou operadoras móveis. Os resultados são cacheados por IP por 1 hora via APCu.
Como adicionar mais usuários ao painel?
Via CLI: php migrate.php add-user email@cliente.com 987654321. O Chat ID do Telegram pode ser encontrado conversando com @userinfobot.
O APCu é obrigatório?
Não. Sem o APCu, o rate limiting e o cache de GeoIP ficam desabilitados. O sistema funciona normalmente, mas cada evento fará uma chamada ao ip-api.com.
Como migrar do v3 para o v4?
A tabela pageviews não é alterada. Execute apenas php migrate.php run para criar as novas tabelas de auth e links compartilhados. Os dados históricos são preservados.