visitor-analytics

Visitor Analytics SDK é uma biblioteca de análise em TypeScript projetada para aplicações web. Funciona com qualquer framework front-end como React, Vue, Svelte, Solid, Astro, bem como com JavaScript vanilla. O SDK enfatiza a privacidade: nunca recolhe informações pessoalmente identificáveis e todos os dados são anonimizados. Funcionalidades principais incluem: - Operação independente de framework com pacotes de integração dedicados para frameworks principais. - Arquitetura modular baseada em plugins que permite colectores, adaptadores de armazenamento e plugins personalizados. - API type-safe com definições estritas em TypeScript e sem tipos 'any'. - Módulos ESM tree-shakable para incluir apenas as partes necessárias. - Dependências zero em tempo de execução e desempenho otimizado usando ouvintes passivos, requestIdleCallback, manipuladores debounceados e leituras em lote do DOM. - Suporte offline com fila que sincroniza quando a rede está disponível, além de repetições com retrocesso exponencial e fallback sendBeacon para descarregamento da página. - Opções configuráveis como tamanho do lote, intervalo de descarga, limites de tentativas, compressão, deduplicação, tempo limite da sessão e campos de dados personalizados. O SDK fornece uma função core createAnalytics que retorna uma instância de análise. A instância oferece métodos para iniciar, parar, descarregar, sincronizar, repetir envios falhados, adicionar ou remover colectores, instalar plugins, consultar registos armazenados, exportar dados, rastrear manualmente alterações de rota, subscrever eventos e destruir a instância. Os colectores reunem uma ampla gama de dados: nome e versão do navegador, sistema operativo e plataforma do dispositivo, dimensões do ecrã, métricas de desempenho (tempo de navegação, tempo de pintura, LCP, CLS, INP), detalhes do ambiente (fuso horário, idioma, esquema de cores), suporte a funcionalidades (WebGL, WebGPU, WASM, Service Worker) e interações do utilizador (duração da sessão, profundidade de deslocamento, contagem de cliques, alterações de rota, parâmetros UTM). Todos os colectores são opcionais e podem ser expandidos com implementações personalizadas. Adaptadores de armazenamento são fornecidos para memória, localStorage e IndexedDB, com capacidade de integrar back-ends personalizados como um adaptador Redis. O carregador agrupa registos, gere repetições com retrocesso exponencial, deduplica lotes e pode comprimir cargas úteis quando o navegador suporta CompressionStream. Exemplos de integração abrangem React (AnalyticsProvider, useAnalytics, usePageView), Vue (createAnalyticsPlugin, useVueAnalytics), Svelte (createAnalyticsStore), SolidJS (AnalyticsProvider, createAnalyticsHook), Astro e JavaScript simples. Cada integração demonstra como inicializar o SDK, aceder aos dados recolhidos e acionar envios manuais. O SDK inclui um sistema de plugins. Os plugins podem registar colectores adicionais ou modificar o comportamento durante a instalação e limpar ao desinstalar. Um exemplo de plugin de teste A/B adiciona a variante experimental atual a cada registo. Garantias de privacidade são explícitas: nunca são recolhidos nomes, emails, palavras-passe, conteúdos de cookies, entradas de formulários, endereços IP exatos, coordenadas GPS, teclas premidas, coordenadas de clique ou quaisquer identificadores persistentes de impressão digital. Identificadores de sessão são UUIDs aleatórios gerados por instância e não são persistidos entre sessões. Limitações conhecidas incluem tempo limite de sessão baseado em atividade, escritas não atómicas ao usar LocalStorage em cenários multi-abas (IndexedDB é recomendado) e compressão gzip opcional que requer suporte recente do navegador. Otimizações de desempenho incluem ouvintes de eventos passivos, requestIdleCallback para trabalho pesado, tratamento debounce de deslocamento e redimensionamento, inicialização preguiçosa de colectores, leituras em lote do DOM via requestAnimationFrame e entrega confiável usando navigator.sendBeacon ao descarregar. O SDK é lançado sob a licença MIT.