@connectabil/analytics-sdk

SDK leve de analytics para tracking de eventos e conversão.

Instalação

Via Git (opção gratuita)

npm install git+https://github.com/connectabilDev/analytics.git#main:packages/sdk

O script prepare constrói automaticamente o diretório dist ao instalar a partir do Git. Gere novas versões com npm version <patch|minor|major> e crie uma tag (git tag vX.Y.Z). Ao apontar para uma tag use #vX.Y.Z:packages/sdk.

Uso Básico

import { Analytics } from '@connectabil/analytics-sdk';

Analytics.init({
  endpoint: 'http://localhost:4001',
  userId: getUserIdFromAuth(),
  enableAutoTracking: true,
  debug: true,
});

Tracking Automático

O SDK rastreia automaticamente:

• Page Views: Todas as visualizações de página
• Clicks: Cliques em elementos (use data-attributes para contexto)
• Scroll Depth: Profundidade máxima de scroll
• Session: Gerenciamento automático de sessão

Data Attributes

Use data-attributes para adicionar contexto aos eventos:

<button
  data-analytics-section="hero"
  data-analytics-action="cta-primary"
  data-analytics-variant="variant-a"
>
  Assinar Premium
</button>

Tracking Manual

const analytics = Analytics.getInstance();

analytics.track('custom_event', {
  category: 'engagement',
  action: 'video_play',
  value: 30,
});

analytics.trackConversion('plan_selection', {
  plan: 'premium-annual',
  value: 499.90,
  currency: 'BRL',
  funnel_step: 2,
});

Configuração

interface AnalyticsConfig {
  endpoint: string;
  apiKey?: string;
  userId?: string;
  sessionTimeout?: number;
  enableAutoTracking?: boolean;
  trackingOptions?: {
    clicks?: boolean;
    scrollDepth?: boolean;
    pageViews?: boolean;
  };
  debug?: boolean;
  batchSize?: number;
  batchInterval?: number;
}

Features

• ✅ Bundle size < 5KB (gzipped)
• ✅ Offline queue com retry
• ✅ Event batching
• ✅ Session management
• ✅ Auto-capture de user_id do URL
• ✅ TypeScript support
• ✅ Zero dependências (exceto uuid)

License

MIT