tracker

O Tracker SDK é uma biblioteca de análise web de tamanho reduzido, projetada para integração rápida em aplicações web modernas, especialmente aquelas geradas por ferramentas assistidas por IA como Vibe Coding. Foca na simplicidade: uma única chamada `init` configura o endpoint do coletor, após o qual pageviews são registradas automaticamente e eventos personalizados podem ser enviados com `track(eventName, data)`. **Principais capacidades** - **Início sem configuração** – Adicionar uma tag script ou um import npm é suficiente para começar a coletar dados. - **Detecção automática de pageviews** – O SDK escuta eventos de navegação e envia um payload `pageview` sem código adicional. - **Tracking de eventos personalizados** – Desenvolvedores podem registrar qualquer interação chamando `track` com um nome e payload opcional. - **Fingerprinting de dispositivo** – Um fingerprint baseado em canvas identifica visitantes de forma única, respeitando a privacidade. - **Fila offline** – Eventos que falham no envio são armazenados no local storage e retryados mais tarde, minimizando perda de dados. - **Gestão de sessões** – Sessões são criadas automaticamente e expiram após um timeout configurável (padrão de 30 minutos). - **Batching configurável** – Eventos são agrupados em uma única requisição para reduzir sobrecarga de rede. **Instalação** - **CDN** – Inclua o bundle UMD diretamente no HTML e chame `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** – `npm install @weavefox/tracker` em seguida importe as funções: `import { init, track, setUserId } from '@weavefox/tracker';`. **API pública** | Método | Finalidade | |--------|---------| | `init(config)` | Inicializa o SDK com endpoint, appId e flags opcionais. | | `track(eventName, data)` | Envia um evento personalizado. | | `trackPageview(data)` | Registra manualmente uma pageview (ativo por padrão). | | `setUserId(userId)` | Associa um usuário logado aos eventos subsequentes. | | `getFingerprint()` | Retorna o fingerprint do dispositivo gerado. | | `flush()` | Dispara imediatamente qualquer evento em fila. | **Opções de configuração** ```javascript WFTK.init({ endpoint: 'obrigatório', // URL do serviço coletor appId: 'opcional', // Identificador da aplicação autoPageview: true, // Auto-track de pageviews debug: false, // Habilita depuração no console enableQueue: true, // Armazena eventos offline quando a rede falha sessionTimeout: 1800000, // Timeout de idle da sessão em ms (padrão 30 min) maxEventsPerSession: 1000 // Limite superior de eventos por sessão }); ``` **Formato do payload** – Cada requisição contém um corpo JSON com um `appId` opcional e um array `events`. Cada evento inclui um nome `event` obrigatório, `timestamp`, `nonce` (para deduplicação), `fingerprint` e um objeto `data` com contexto coletado pelo sistema (URL, título, informações do dispositivo, etc.). Campos definidos pelo usuário pertencem ao sub-objeto `biz`, mantendo análises e dados de negócio separados. **Considerações do lado do servidor** - **Validação de timestamp** – Rejeite eventos com mais de 5 minutos para prevenir replay attacks. - **Deduplicação por nonce** – Armazene nonces (por exemplo, em Redis) com TTL de 24 horas para garantir idempotência. - **Rate limiting** – Aplique limites por IP e por fingerprint para coibir abuso. - **Identificação do app** – Prefira um `appId` explícito no payload; fallback para o host do `Referer` da requisição se necessário. - **Handler Express de exemplo** – O README fornece um snippet conciso em Node.js que valida timestamps, verifica nonces e persiste eventos. **Licença** – Distribuído sob a licença MIT, permitindo uso irrestrito em projetos open-source e comerciais. No geral, o Tracker SDK oferece uma solução simples e consciente da privacidade para desenvolvedores que precisam de análise client-side confiável sem a sobrecarga de plataformas pesadas.