GomarkePixel

SDK de tracking para web com arquitetura modular:

• Core: visitante, sessão, pageview, fila, retry, flush e HCID na URL
• Behavior: scroll, click, rage click, idle, visibility, exit intent, viewport e engagement
• Conversion: eventos de conversão/e-commerce (manual e automático)
• AutoTrackers: detecção por seletores, heurísticas de formulário e data-attributes
• AutoTrack Engine: regras leves por seletor, texto e padrão de URL

Official Playground

O único exemplo oficial do projeto é o Playground — documentação viva, ambiente de QA e smoke test manual com cobertura completa das APIs públicas.

pnpm build
# Sirva a pasta do projeto (ex.: npx serve .) e abra:
# examples/official-playground.html

O Playground inclui:

| Módulo | O que valida | |--------|----------------| | Header | Versão, Pixel ID, Visitor, Session, HCID, fila, endpoint, flush, reset | | Core | Bootstrap, sessão, fila, telemetria, consent, runtime snapshot | | Behavior | Scroll, click, rage click, idle, visibility, exit intent, engagement, viewport | | Produtos + Carrinho | Catálogo, cupom, AutoAddToCart / AutoRemoveToCart | | Checkout | Fluxo completo Produto → Carrinho → Customer → Shipping → Pagamento → Confirmação | | Customer | AutoCustomerTracker, CustomerDataStore em tempo real, AutoCustomerAddToCart | | Pagamento | AutoAddPaymentInfo (cartão), PIX e boleto (visual) | | AutoTrackers | Status de todos os trackers + factory stats | | Conversão manual | Todos os métodos track* públicos | | Viewport | Elementos data-viewport-key com intersection/click/hover | | HCID | URL antes/depois do history.replaceState() | | AutoTrack Engine | Seletor, texto e URL pattern | | Debug Panel | Event Inspector, logs exportáveis, estado da fila |

Eventos são interceptados para https://playground.mock/gomarke — nenhuma chamada real ao backend é necessária para testar.

Para uso programático em TypeScript, veja também examples/usage-example.ts.

Instalação

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

CDN (global)

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

Modos de uso

Script tag com auto-init

Com data-pixel, o SDK faz bootstrap e expõe window.gomarkePixel:

<script
  src="../dist/index.global.js"
  data-pixel="pix_123"
  data-api-endpoint="https://seu-endpoint"
  data-debug="true"
  data-project-id="projeto"
  data-page-id="home"
></script>

Veja o script tag completo em examples/official-playground.html.

Import por módulo

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

const pixel = new GomarkePixel({
  pixel: 'pix_123',
  apiEndpoint: 'https://seu-endpoint',
  debug: true,
});

Configuração (GomarkePixelConfig)

Principais blocos (detalhes no Playground e em src/types.ts):

• behavior — Behavior Engine + viewport
• autoTracks — AutoAddToCart, AutoLead, AutoAddPaymentInfo, AutoCustomer, etc.
• autoTrack — regras por seletor, texto e URL

Customer AutoTracker (novo)

autoTracks: {
  customer: {
    enabled: true,
    autoAddToCart: true, // dispara ADD_TO_CART quando email + phone existem
    debounceMs: 300,
    selectors: { email: '#custom-email' }, // opcional
  },
  addPaymentInfo: { enabled: true }, // enriquece payload com CustomerDataStore
}

Métodos públicos — GomarkePixel

Conversão (track manual)

• trackPageView()
• trackViewContent(data?)
• trackSearch({ searchTerm, ... })
• trackAddToCart({ itemId, itemName, customer?, ... })
• trackRemoveToCart({ itemId, itemName, ... })
• trackInitiateCheckout({ value?, currency?, items? })
• trackLead({ email, name, phone, message })
• trackAddPaymentInfo({ paymentMethod?, customer?, ... })
• trackPurchase({ value, currency, transactionId?, items? })

Nota: CompleteRegistration, Subscribe e Contact não possuem track* dedicado. No Playground são demonstrados via trackLead com metadados ou trackWithParams no PageView tracker (padrão documentado na seção Conversão Manual).

Core / fila / debug

• getSessionId(), getVisitorId(), getSessionData(), isSessionActive()
• getQueueLength(), getQueueStats(), getQueueTelemetry(), flushQueue()
• getRuntimeDebugSnapshot(), getDeadLetterCount(), exportDeadLetterData()
• clearSession(), renewSession(), exportSessionData()

Behavior

• getBehaviorState(), getBehaviorPhase(), getViewportState()
• enqueueBehaviorSnapshot(), getBehaviorBufferStats(), getBehaviorBatchPayload()
• resetForNewPage() (SPA)

AutoTrackers (setup)

• setupAutoViewContent(), setupAutoAddToCart(), setupAutoRemoveToCart()
• setupAutoInitiateCheckout(), setupAutoAddPaymentInfo(), setupAutoLead()
• getAutoTrackerFactory(), getAutoTrackerStats(), rebuildAllAutoTrackers(), stopAllAutoTrackers()

Customer é inicializado via autoTracks.customer na config (veja Playground).

Factories

• getTrackerFactory() — acesso direto aos trackers (trackWithCustomParams, trackMultipleItems, etc.)

Fluxo de conversão

PAGE_VIEW → VIEW_CONTENT → ADD_TO_CART → INITIATE_CHECKOUT → ADD_PAYMENT_INFO → PURCHASE

O Playground executa esse funil de ponta a ponta com AutoTrackers e checkout HTML.

HCID na URL

Após criar a sessão, o Core sincroniza ?hcid={sessionId} via history.replaceState() (sem reload). Valide na seção HCID do Playground.

data-attributes padrão

| Evento | Atributo | |--------|----------| | Add to cart | data-add-to-cart + data-product-* | | Remove from cart | data-remove-from-cart | | Checkout | data-checkout + data-cart-* | | Lead | data-lead | | View content | data-view-content | | Viewport | data-viewport-key | | Add payment info | detecção heurística de campos de cartão | | Customer | detecção heurística de campos do formulário |

Uso com React / Next.js

Padrão idêntico ao documentado anteriormente — substitua qualquer referência a exemplos HTML antigos por:

1. Configuração espelhando examples/official-playground.html
2. Integração programática em examples/usage-example.ts

Scripts de desenvolvimento

pnpm dev
pnpm build
pnpm test
pnpm type-check

Estrutura de módulos

src/
  core/           # visitor, session, pageview, queue, consent, HCID
  behavior/       # scroll, click, idle, viewport, engagement
  conversion/     # engine, tracks, autoTracks, customer/
  utils/          # sessão, envio, UrlSessionSync, getSetting
  pixel.ts        # GomarkePixel
  index.ts        # exports públicos
examples/
  official-playground.html   # único exemplo HTML oficial
  usage-example.ts           # exemplo TypeScript / factories

Licença

MIT