Sobre o projeto

Clamp Analytics é um SDK JavaScript leve que permite coletar dados de uso do produto sem cookies ou identificadores pessoais. Após inicializar a biblioteca com seu ID de projeto, as visualizações de página e as informações de sessão são registradas automaticamente, e você pode enviar eventos personalizados, identificar usuários logados, capturar transações de receita e registrar erros. A instalação é simples: adicione o pacote com npm ou cole uma única tag de script que aponta para o CDN. O script lê o identificador do projeto de um atributo data‑clamp‑project e começa a rastrear imediatamente. Para frameworks como React, Next.js, Vite, Nuxt, SvelteKit, Astro e outros, o SDK fornece guias dedicados e um componente React que pode ser colocado no layout raiz. A API inclui init, track, identify, reset, revenue, getAnonymousId e getUserId. Track permite registrar qualquer evento nomeado com propriedades de chave-valor simples. Revenue é um auxiliar tipado que emite eventos canônicos de assinatura e compra, calculando automaticamente as variações da receita recorrente mensal (MRR) com base no período de faturamento. Identify vincula um ID de usuário estável a eventos futuros, enquanto reset limpa a associação ao fazer logout. Mapas de eventos tipados podem ser definidos em TypeScript, fornecendo autocompletar e validação em tempo de compilação para eventos personalizados. Os eventos de receita seguem um tipo de união estrito que impõe a combinação correta de campos para assinaturas, compras únicas e reembolsos. O tratamento de erros pode ser ativado para capturar exceções não tratadas e rejeições de promessas não manipuladas como eventos $error, que são agrupados por fingerprint para uma análise mais fácil. Extensões opcionais adicionam rastreamento automático para links externos, downloads de arquivos, páginas 404, eventos acionados por atributos de dados, web vitals e visibilidade de visualização de seção. Cada extensão é carregada sob demanda, mantendo o tamanho do bundle mínimo. O uso server‑side é suportado através de uma build separada que requer uma chave de API. Você pode emitir os mesmos eventos de serviços de backend, webhooks ou ações de servidor, garantindo um fluxo de eventos unificado. Todos os dados coletados são armazenados na plataforma Clamp Analytics, que oferece um nível gratuito de 100 mil eventos por mês e um servidor Model Context Protocol integrado. Isso torna os eventos diretamente consultáveis por agentes de IA como Claude, Cursor ou extensões do VS Code, permitindo análises em linguagem natural e insights automatizados. O SDK é lançado sob a licença MIT e é mantido no repositório clamp‑sh/analytics.