📊 @racoelho/analytics

SDK leve (~3KB) para analytics web. Funciona em React, Angular e VanillaJS.

📦 Instalação

npm install @racoelho/analytics

CDN: https://cdn.jsdelivr.net/npm/@racoelho/analytics/dist/index.global.js

🚀 Uso Rápido

import { Analytics } from '@racoelho/analytics'

const analytics = new Analytics({
  siteKey: 'pk_demo',           // obrigatório
  endpoint: 'https://.../v1/i', // obrigatório
  batchSize: 10,                // opcional, default: 10
  flushIntervalMs: 3000,        // opcional, default: 3000
  respectDNT: true,             // opcional, default: true
  autoPageview: true            // opcional, default: true
})

// Eventos são enviados automaticamente em batch
analytics.track('button_click', { id: 'cta' })

📋 Métodos Disponíveis

Métodos Principais

| Método | Parâmetros | Descrição | |--------|------------|-----------| | track(name, props?) | name: stringprops?: object | Evento customizado | | pageview(props?) | props?: object | Visualização de página | | identify(payload) | { user_id: string, traits?: object } | Identificar usuário | | setConsent(status) | 'granted' \| 'denied' | Consentimento LGPD/GDPR | | flush() | - | Forçar envio imediato |

Eventos Padronizados

Interação

• click(elementId?, elementText?, props?)

Formulários

• formStart(formId?, formName?, props?)
• formSubmit(formId?, formName?, props?)

Download/Share

• download(fileName?, fileType?, props?)
• share(method?, contentType?, itemId?, props?)

Busca

• search(query?, category?, props?)

Autenticação

• signup(method?, props?)
• login(method?, props?)
• logout(props?)

E-commerce

• viewItem(productId?, productName?, category?, price?, props?)
• addToCart(productId?, productName?, price?, quantity?, props?)
• removeFromCart(productId?, productName?, props?)
• beginCheckout(value?, currency?, props?)
• purchase(orderId?, value?, currency?, items?, props?) items: Array<{ product_id?, product_name?, price?, quantity? }>

Vídeo

• videoPlay(videoId?, videoTitle?, duration?, props?)
• videoPause(videoId?, currentTime?, props?)
• videoComplete(videoId?, duration?, props?)

Navegação

• scroll(depth?, props?)

Nota: Todos os parâmetros são opcionais. Use props para adicionar propriedades customizadas.

💡 Exemplos

// E-commerce
analytics.viewItem('prod-123', 'Notebook', 'eletrônicos', 2999.99)
analytics.addToCart('prod-123', 'Notebook', 2999.99, 1)
analytics.purchase('order-456', 2999.99, 'BRL', [
  { product_id: 'prod-123', product_name: 'Notebook', price: 2999.99, quantity: 1 }
])

// Autenticação
analytics.signup('email', { plan: 'premium' })
analytics.login('google')

// Vídeo
analytics.videoPlay('video-123', 'Tutorial', 1800)
analytics.videoPause('video-123', 450)
analytics.videoComplete('video-123', 1800)

// Formulário
analytics.formStart('contact-form', 'Contato')
analytics.formSubmit('contact-form', 'Contato', { fields: 5 })

// Busca
analytics.search('typescript', 'docs')

// Customizado
analytics.track('newsletter_signup', { source: 'footer' })

🔧 Configuração

| Opção | Tipo | Default | Descrição | |-------|------|---------|-----------| | siteKey | string | - | Obrigatório. Chave do site | | endpoint | string | - | Obrigatório. URL do endpoint | | batchSize | number | 10 | Eventos por batch | | flushIntervalMs | number | 3000 | Intervalo de flush (ms) | | respectDNT | boolean | true | Respeitar Do Not Track | | autoPageview | boolean | true | Pageview automático |

📊 Payload Automático

Cada evento inclui automaticamente:

• ts, url, path, referrer
• anon_id, session_id, user_id (se identificado)
• lang, tz, viewport, screen
• utm (se presente na URL)
• props (customizado)

Header automático: x-country (detectado via browser)

🔒 Privacidade

• Respeita navigator.doNotTrack === '1'
• Sistema de consent: analytics.setConsent('granted' | 'denied')
• Armazena apenas anon_id (localStorage) e session_id (sessionStorage)
• Sem cookies de terceiros

🚀 Batching

Eventos são agrupados automaticamente:

• Flush quando atinge batchSize eventos
• Flush a cada flushIntervalMs ms
• Flush em visibilitychange e beforeunload
• Deduplicação automática (500ms)

📄 Licença

MIT © Rafael Coelho