@agenus-io/pixel

v0.0.4

Published

15 days ago

Pixel Tracker para Facebook e Google Analytics - Envia eventos para sua API do Agenus

0High
0Medium
0Low

davidpimenta

agenus.io

pixel tracking facebook google-analytics ecommerce analytics cdn iife typescript

GomarkePixel

Pixel Tracker avançado para Facebook e Google Analytics - Envia eventos para sua API do Agenus via sendBeacon (com fallback para fetch). Inclui sistema de auto-tracking inteligente com arquitetura orientada a objetos e máxima escalabilidade.

🚀 Instalação

Via CDN (Recomendado)

<script src="https://unpkg.com/@agenus-io/pixel@latest/dist/index.global.js"></script>

Via NPM

npm install @agenus-io/pixel
# ou
pnpm add @agenus-io/pixel
# ou
yarn add @agenus-io/pixel

📖 Uso

🚀 Auto-Tracking Automático - Configure Uma Vez e Esqueça!

O GomarkePixel agora funciona de forma completamente automática! Você só precisa configurar uma vez e todos os eventos são detectados automaticamente.

Uso Global (CDN) - Auto-Tracking Automático

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@agenus-io/pixel@latest/dist/index.global.js"></script>
  </head>
  <body>
    <!-- Elementos com data attributes para auto-tracking -->
    <button
      data-add-to-cart
      data-product-id="123"
      data-product-name="iPhone 15"
      data-product-price="8999"
    >
      Adicionar ao Carrinho
    </button>

    <button data-checkout data-cart-total="8999">Finalizar Compra</button>

    <form data-lead>
      <input name="email" placeholder="Email" required />
      <input name="name" placeholder="Nome" required />
      <button type="submit">Enviar</button>
    </form>

    <script>
      // Inicializar o pixel tracker com auto-tracking
      const pixel = new GomarkePixel({
        apiEndpoint: 'https://sua-api.com/track',
        apiKey: 'sua-chave-aqui',
        debug: true,

        // Configuração de auto-tracking - TUDO AUTOMÁTICO! 🚀
        autoTracks: {
          addToCart: {
            enabled: true,
            selector: '[data-add-to-cart]',
            selectorType: 'attribute',
            productDataSelectors: {
              id: '[data-product-id]',
              name: '[data-product-name]',
              price: '[data-product-price]',
            },
          },
          initiateCheckout: {
            enabled: true,
            selector: '[data-checkout]',
            selectorType: 'attribute',
            cartDataSelectors: {
              total: '[data-cart-total]',
            },
          },
          lead: {
            enabled: true,
            selector: 'form[data-lead]',
            selectorType: 'attribute',
            requiredFields: ['email', 'name'],
          },
          scroll: {
            enabled: true,
            scrollThresholds: [25, 50, 75, 90],
          },
        },
      });

      // Page view é automático, mas você ainda pode usar manualmente se quiser
      // pixel.trackPageView();
      // pixel.trackAddToCart('produto-123', 'Produto Exemplo', 99.90, 'BRL', 'Categoria');
      // pixel.trackPurchase(199.90, 'BRL', 'txn_123');
    </script>
  </body>
</html>

Uso em Módulos - Auto-Tracking Automático

import GomarkePixel from '@agenus-io/pixel';

const pixel = new GomarkePixel({
  apiEndpoint: 'https://sua-api.com/track',
  apiKey: 'sua-chave-aqui',
  debug: true,

  // Auto-tracking automático - configure uma vez e esqueça! 🚀
  autoTracks: {
    addToCart: {
      enabled: true,
      selector: '.add-to-cart-btn',
      selectorType: 'class',
      productDataSelectors: {
        id: '.product-id',
        name: '.product-name',
        price: '.product-price',
        category: '.product-category',
      },
    },
    initiateCheckout: {
      enabled: true,
      selector: '.checkout-btn',
      selectorType: 'class',
      trackOnNavigation: true,
      navigationSelectors: ['.checkout-link', '.finalizar-compra'],
    },
    lead: {
      enabled: true,
      selector: 'form.contact-form',
      selectorType: 'class',
      trackOnFieldFocus: true,
      requiredFields: ['email', 'name'],
      validationRules: {
        email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      },
    },
    scroll: {
      enabled: true,
      scrollThresholds: [25, 50, 75, 90],
      trackScrollDepth: true,
      trackTimeOnPage: true,
    },
    viewport: {
      enabled: true,
      selector: '.trackable-element',
      selectorType: 'class',
      trackElementIntersection: true,
      trackElementClicks: true,
    },
  },
});

// Page view é automático! Os autoTracks detectam tudo sozinhos
// Não precisa chamar manualmente:
// await pixel.trackPageView();
// await pixel.trackAddToCart('produto-123', 'Produto Exemplo', 99.90);

🔧 Configuração

Configuração Básica (Sem Auto-Tracking)

interface GomarkePixelConfig {
  apiEndpoint: string; // URL da sua API (obrigatório)
  apiKey?: string; // Chave de autenticação
  debug?: boolean; // Ativar logs de debug
  timeout?: number; // Timeout para requests (padrão: 5000ms)
}

Configuração com Auto-Tracking Automático

interface GomarkePixelConfig {
  apiEndpoint: string;
  apiKey?: string;
  debug?: boolean;
  timeout?: number;

  // 🚀 AUTO-TRACKING - Configure uma vez e esqueça!
  autoTracks?: {
    addToCart?: {
      enabled?: boolean;
      selector?: string;
      selectorType?:
        | 'class'
        | 'id'
        | 'attribute'
        | 'tag'
        | 'text'
        | 'url'
        | 'data-attribute'
        | 'custom';
      productDataSelectors?: {
        id?: string;
        name?: string;
        price?: string;
        category?: string;
        image?: string;
      };
    };
    initiateCheckout?: {
      enabled?: boolean;
      selector?: string;
      selectorType?:
        | 'class'
        | 'id'
        | 'attribute'
        | 'tag'
        | 'text'
        | 'url'
        | 'data-attribute'
        | 'custom';
      trackOnNavigation?: boolean;
      navigationSelectors?: string[];
    };
    lead?: {
      enabled?: boolean;
      selector?: string;
      selectorType?:
        | 'class'
        | 'id'
        | 'attribute'
        | 'tag'
        | 'text'
        | 'url'
        | 'data-attribute'
        | 'custom';
      trackOnFieldFocus?: boolean;
      trackOnFieldBlur?: boolean;
      trackOnFieldChange?: boolean;
      requiredFields?: string[];
      validationRules?: {
        email?: RegExp;
        phone?: RegExp;
        minLength?: number;
      };
    };
    scroll?: {
      enabled?: boolean;
      scrollThresholds?: number[];
      trackScrollDepth?: boolean;
      trackTimeOnPage?: boolean;
    };
    viewport?: {
      enabled?: boolean;
      selector?: string;
      selectorType?:
        | 'class'
        | 'id'
        | 'attribute'
        | 'tag'
        | 'text'
        | 'url'
        | 'data-attribute'
        | 'custom';
      trackElementIntersection?: boolean;
      trackElementClicks?: boolean;
      trackElementHovers?: boolean;
    };
  };
}

📚 API - Eventos de E-commerce

Eventos Principais (Tracks)

trackPageView(page?: string): Track page view
trackPurchase(value, currency, transactionId?, items?): Track compra
trackAddToCart(itemId, itemName, value?, currency?, category?, quantity?): Adicionar ao carrinho
trackRemoveFromCart(itemId, itemName, value?, currency?, quantity?): Remover do carrinho
trackInitiateCheckout(value?, currency?, items?): Iniciar checkout
trackViewItem(itemId, itemName, value?, currency?, category?): Ver produto
trackSearch(searchTerm, resultsCount?): Busca
trackCustomEvent(eventName, eventCategory?, value?, currency?, customParameters?): Evento customizado

Auto-Tracking Inteligente

O GomarkePixel agora inclui um sistema avançado de auto-tracking que detecta automaticamente interações do usuário:

AutoTracks Básicos

AutoAddToCart: Detecta automaticamente cliques em botões "Adicionar ao Carrinho"
AutoInitiateCheckout: Detecta automaticamente cliques em botões "Finalizar Compra"
AutoLead: Detecta automaticamente submissões de formulários de lead

AutoTracks Avançados

ScrollTracker: Rastreia profundidade de scroll e tempo na página
ViewportTracker: Detecta quando elementos entram/saem do viewport

Configuração de AutoTracks

// Configurar auto-tracking
const pixel = new GomarkePixel({
  apiEndpoint: 'https://sua-api.com/track',
  apiKey: 'sua-chave',
  debug: true,
});

// Auto-tracking de Add to Cart
await pixel
  .getTrackerFactory()
  .getAutoTrackerFactory()
  .createAddToCartTracker({
    isEnabled: true,
    selector: '.add-to-cart-btn',
    selectorType: 'class',
    productDataSelectors: {
      id: '.product-id',
      name: '.product-name',
      price: '.product-price',
      category: '.product-category',
    },
  });

// Auto-tracking de Checkout
await pixel
  .getTrackerFactory()
  .getAutoTrackerFactory()
  .createInitiateCheckoutTracker({
    isEnabled: true,
    selector: '.checkout-btn',
    selectorType: 'class',
    trackOnNavigation: true,
    navigationSelectors: ['.checkout-link', '.finalizar-compra'],
  });

// Auto-tracking de Lead
await pixel
  .getTrackerFactory()
  .getAutoTrackerFactory()
  .createLeadTracker({
    isEnabled: true,
    selector: 'form.lead-form',
    selectorType: 'class',
    trackOnFieldFocus: true,
    trackOnFieldBlur: true,
    requiredFields: ['email', 'name'],
  });

Exemplo Completo

const pixel = new GomarkePixel({
  apiEndpoint: 'https://sua-api.com/track',
  apiKey: 'sua-chave',
  debug: true,
});

// Page view automático
// Track view de produto
await pixel.trackViewItem(
  'produto-123',
  'iPhone 15',
  8999,
  'BRL',
  'Smartphones'
);

// Adicionar ao carrinho
await pixel.trackAddToCart(
  'produto-123',
  'iPhone 15',
  8999,
  'BRL',
  'Smartphones',
  1
);

// Iniciar checkout
await pixel.trackInitiateCheckout(8999, 'BRL', [
  {
    item_id: 'produto-123',
    item_name: 'iPhone 15',
    category: 'Smartphones',
    quantity: 1,
    price: 8999,
  },
]);

// Finalizar compra
await pixel.trackPurchase(8999, 'BRL', 'txn_123', [
  {
    item_id: 'produto-123',
    item_name: 'iPhone 15',
    category: 'Smartphones',
    quantity: 1,
    price: 8999,
  },
]);

🛠️ Desenvolvimento

Instalação das Dependências

pnpm install

Scripts Disponíveis

# Desenvolvimento com watch
pnpm dev

# Build para produção
pnpm build

# Linting
pnpm lint
pnpm lint:fix

# Formatação
pnpm format

# Verificação de tipos
pnpm type-check

Estrutura do Projeto

src/
├── index.ts                    # Ponto de entrada principal
├── config.ts                   # Configurações globais
├── types.ts                    # Definições de tipos
├── utils/                      # Utilitários
│   ├── getFingerprint.ts
│   └── sendEvent.tsx
├── tracks/                     # Sistema de tracking manual
│   ├── BaseTracker.ts          # Classe base para todos os trackers
│   ├── pageView.ts
│   ├── purchase.ts
│   ├── addToCart.ts
│   ├── initiateCheckout.ts
│   ├── lead.ts
│   ├── TrackerFactory.ts       # Factory para gerenciar trackers
│   └── index.ts
├── autoTracks/                 # Sistema de auto-tracking
│   ├── BaseAutoTracker.ts      # Classe base para auto-trackers
│   ├── autoAddToCart.ts        # Auto-tracking de adicionar ao carrinho
│   ├── autoInitiateCheckout.ts # Auto-tracking de checkout
│   ├── autoLead.tsx            # Auto-tracking de leads
│   ├── AutoTrackerFactory.ts   # Factory para auto-trackers
│   ├── utils/                  # Utilitários para auto-tracking
│   │   ├── SelectorUtils.ts    # Utilitários de seleção DOM
│   │   └── EventManager.ts     # Gerenciador de eventos
│   ├── advanced/               # Auto-trackers avançados
│   │   ├── ScrollTracker.ts    # Rastreamento de scroll
│   │   └── ViewportTracker.ts  # Rastreamento de viewport
│   └── index.ts
└── examples/                   # Exemplos de uso
    ├── usage-example.ts
    └── autotrack-usage-example.ts

dist/                          # Arquivos compilados
├── index.global.js           # Versão IIFE para CDN
├── index.cjs.js              # CommonJS
├── index.esm.js              # ES Modules
├── index.d.ts                # Definições TypeScript
└── index.d.mts               # Definições TypeScript (ESM)

✨ Por que Auto-Tracking?

🎯 Configure Uma Vez, Funcione Para Sempre

Zero Código Manual: Não precisa chamar trackAddToCart(), trackLead(), etc.
Detecção Automática: Detecta cliques, formulários, scroll, viewport automaticamente
DOM Dinâmico: Funciona com elementos adicionados via JavaScript/AJAX
Performance Otimizada: Debouncing, throttling e lazy loading automáticos
Validação Inteligente: Valida formulários automaticamente
Retry Logic: Tenta novamente se elementos ainda não carregaram

🚀 Exemplo: Antes vs Depois

❌ Antes (Manual)

// Tinha que chamar manualmente para cada evento
pixel.trackPageView();
document.querySelector('.add-to-cart').addEventListener('click', () => {
  pixel.trackAddToCart('produto-123', 'Produto', 99.9);
});
document.querySelector('form').addEventListener('submit', () => {
  pixel.trackLead({ email: '[email protected]' });
});
// ... mais código manual para cada interação

✅ Depois (Automático)

// Configure uma vez e esqueça!
const pixel = new GomarkePixel({
  apiEndpoint: 'https://sua-api.com/track',
  autoTracks: {
    addToCart: { enabled: true, selector: '[data-add-to-cart]' },
    lead: { enabled: true, selector: 'form[data-lead]' },
    scroll: { enabled: true },
  },
});
// TUDO FUNCIONA AUTOMATICAMENTE! 🎉

🏗️ Arquitetura Avançada

Sistema de Classes Orientado a Objetos

O GomarkePixel foi completamente refatorado para usar uma arquitetura orientada a objetos com máxima escalabilidade:

Tracks (Tracking Manual)

BaseTracker: Classe abstrata base para todos os trackers
TrackerFactory: Factory pattern para gerenciar instâncias de trackers
PageViewTracker, PurchaseTracker, AddToCartTracker, etc.

AutoTracks (Tracking Automático)

BaseAutoTracker: Classe abstrata base para auto-trackers
AutoTrackerFactory: Factory pattern para gerenciar auto-trackers
SelectorUtils: Utilitários avançados para seleção DOM
EventManager: Gerenciador de eventos com debouncing/throttling

Funcionalidades Avançadas

🎯 Auto-Tracking Inteligente

Detecção Automática: Detecta interações sem configuração manual
DOM Dinâmico: Suporte a elementos adicionados dinamicamente via MutationObserver
Retry Logic: Sistema de retry automático para elementos que ainda não carregaram
Debouncing/Throttling: Otimização de performance para eventos frequentes

🔧 Configuração Flexível

Múltiplos Seletores: Suporte a class, id, attribute, tag, text, url, data-attribute, custom
Extração de Dados: Seletores configuráveis para extrair dados de produtos/carrinho
Validação: Sistema de validação de formulários
Callbacks Customizados: Funções de callback para processamento customizado

📊 Estatísticas e Monitoramento

Estatísticas Detalhadas: Contadores de eventos, performance, erros
Debug Avançado: Logs detalhados para desenvolvimento
Health Checks: Verificação de saúde dos trackers

🚀 Performance

Lazy Loading: Carregamento sob demanda de auto-trackers
Memory Management: Limpeza automática de listeners
Bundle Optimization: Tree-shaking para reduzir tamanho do bundle

📦 Build

O projeto usa tsup para gerar múltiplos formatos:

IIFE (.global.js): Para uso via CDN
CommonJS (.cjs.js): Para Node.js
ES Modules (.esm.js): Para bundlers modernos
TypeScript (.d.ts): Definições de tipos

🎯 Exemplos Avançados

Auto-Tracking Completo para E-commerce

const pixel = new GomarkePixel({
  apiEndpoint: 'https://sua-api.com/track',
  apiKey: 'sua-chave',
  debug: true,
});

// Configurar todos os auto-trackers
const autoFactory = pixel.getTrackerFactory().getAutoTrackerFactory();

// Auto-tracking de produtos
await autoFactory.createAddToCartTracker({
  isEnabled: true,
  selector: '[data-add-to-cart]',
  selectorType: 'attribute',
  productDataSelectors: {
    id: '[data-product-id]',
    name: '.product-title',
    price: '.price-value',
    category: '.product-category',
  },
  customDataExtractor: element => ({
    brand: element.dataset.brand,
    variant: element.dataset.variant,
  }),
});

// Auto-tracking de checkout
await autoFactory.createInitiateCheckoutTracker({
  isEnabled: true,
  selector: '.checkout-button',
  selectorType: 'class',
  trackOnNavigation: true,
  navigationSelectors: ['.checkout-link', '.finalizar-compra'],
  cartDataSelectors: {
    total: '.cart-total',
    currency: '.cart-currency',
    items: '.cart-item',
  },
});

// Auto-tracking de leads
await autoFactory.createLeadTracker({
  isEnabled: true,
  selector: 'form.contact-form',
  selectorType: 'class',
  trackOnFieldFocus: true,
  trackOnFieldBlur: true,
  trackOnFieldChange: true,
  requiredFields: ['email', 'name'],
  validationRules: {
    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
    phone: /^\(\d{2}\)\s\d{4,5}-\d{4}$/,
  },
});

Auto-Tracking Avançado

// Scroll tracking
const scrollTracker = new ScrollTracker(
  pixel.config,
  pixel.sessionId,
  pixel.version
);
await scrollTracker.initialize({
  isEnabled: true,
  scrollThresholds: [25, 50, 75, 90],
  trackScrollDepth: true,
  trackTimeOnPage: true,
  debounceMs: 300,
});

// Viewport tracking
const viewportTracker = new ViewportTracker(
  pixel.config,
  pixel.sessionId,
  pixel.version
);
await viewportTracker.initialize({
  isEnabled: true,
  selector: '.trackable-element',
  selectorType: 'class',
  trackElementIntersection: true,
  trackElementClicks: true,
  trackElementHovers: true,
  visibilityThreshold: 0.5,
  maxTrackingElements: 100,
});

Monitoramento e Estatísticas

// Obter estatísticas dos trackers
const stats = pixel.getTrackerStats();
console.log('Estatísticas dos trackers:', stats);

// Obter estatísticas dos auto-trackers
const autoStats = pixel
  .getTrackerFactory()
  .getAutoTrackerFactory()
  .getFactoryStats();
console.log('Estatísticas dos auto-trackers:', autoStats);

// Parar todos os auto-trackers
await pixel.getTrackerFactory().getAutoTrackerFactory().stopAllAutoTrackers();

// Reconstruir todos os auto-trackers (útil para DOM dinâmico)
await pixel
  .getTrackerFactory()
  .getAutoTrackerFactory()
  .rebuildAllAutoTrackers();

🚀 Publicação

# Build antes de publicar
pnpm build

# Publicar no NPM
npm publish

🆕 Changelog

v2.0.0 - Refatoração Completa

✨ Novas Funcionalidades

Sistema de Auto-Tracking: Detecção automática de interações do usuário
Arquitetura Orientada a Objetos: Classes base e factory patterns
AutoTracks Avançados: ScrollTracker e ViewportTracker
Sistema de Seletores: Suporte a múltiplos tipos de seletores
Extração de Dados: Seletores configuráveis para dados de produtos
Validação de Formulários: Sistema de validação com regras customizadas
Monitoramento: Estatísticas detalhadas e health checks

🔧 Melhorias Técnicas

TypeScript: Tipagem completa e type safety
Performance: Debouncing, throttling e lazy loading
DOM Dinâmico: Suporte a elementos adicionados dinamicamente
Retry Logic: Sistema de retry automático
Memory Management: Limpeza automática de listeners
Bundle Optimization: Tree-shaking e otimizações

🏗️ Arquitetura

BaseTracker: Classe base para trackers manuais
BaseAutoTracker: Classe base para auto-trackers
TrackerFactory: Factory para gerenciar trackers
AutoTrackerFactory: Factory para gerenciar auto-trackers
SelectorUtils: Utilitários avançados de seleção DOM
EventManager: Gerenciador de eventos otimizado

📊 Monitoramento

Estatísticas Detalhadas: Contadores de eventos e performance
Debug Avançado: Logs detalhados para desenvolvimento
Health Checks: Verificação de saúde dos trackers
Error Handling: Tratamento robusto de erros

📄 Licença

MIT