SDK Analytics

Visão Geral

O SDK de Analytics da FoxPixel fornece tracking automático de visitantes, sessões e eventos no seu site. Funciona sem cookies, respeitando a privacidade dos utilizadores e o GDPR/LGPD.

Instalação

O script de analytics é incluído automaticamente no site-template. Se estiver a construir um site custom, adicione o script:

<script
  src="https://api.usefoxpixel.com/foxpixel-analytics.js"
  data-site-id="SEU_TENANT_ID"
  defer
></script>

Ou no Next.js:

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://api.usefoxpixel.com/foxpixel-analytics.js"
          data-site-id="SEU_TENANT_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

O que é rastreado automaticamente

Evento	Quando	Dados recolhidos
Pageview	Cada carregamento de página	URL, título, referrer, UTM params
Navegação SPA	Mudança de rota (pushState/replaceState)	Nova URL, título anterior, título novo
Dados do dispositivo	Em cada evento	Tipo (desktop/mobile/tablet), browser, OS, resolução
UTM Parameters	Se presentes na URL	source, medium, campaign, term, content

Eventos Custom

Rastreie ações específicas dos utilizadores:

// Básico
foxpixel.track('click', 'cta_hero');

// Com propriedades
foxpixel.track('click', 'add_to_cart', {
  productId: '123',
  productName: 'Produto X',
  price: 29.99
});

// Form submit
foxpixel.track('form_submit', 'newsletter', {
  formId: 'footer-newsletter',
  email: 'user@example.com'
});

// Scroll depth
foxpixel.track('scroll', 'page_50', {
  percentage: 50,
  page: window.location.pathname
});

Assinatura da função

foxpixel.track(
  eventType: string,    // Tipo do evento (click, form_submit, scroll, custom)
  eventName: string,    // Nome identificador do evento
  properties?: object   // Propriedades adicionais (opcional)
): void

Identificação do Visitante

O SDK usa fingerprinting do browser para identificar visitantes, sem cookies:

Storage	Chave	Duração	Conteúdo
`localStorage`	`_fp_vid`	Permanente	Hash FNV-1a (canvas + UA + screen + timezone)
`sessionStorage`	`_fp_sid`	Até fechar o tab	UUID aleatório

Aceder ao visitorId

// Obter o visitor ID (útil para integrar com checkout)
const visitorId = localStorage.getItem('_fp_vid');

O visitorId identifica um browser, não um utilizador. O mesmo utilizador em Chrome e Safari = dois visitantes diferentes.

O tracking respeita as preferências de consentimento do utilizador.

Fluxo automático

Se o banner GDPR está ativado no Tenant Admin, o script espera pelo consentimento
Quando o utilizador aceita, o consentimento é guardado em localStorage
O script começa a rastrear

Controlo programático

// Dar consentimento
function acceptAll() {
  localStorage.setItem('foxpixel_consent', JSON.stringify({
    essential: true,
    analytics: true,
    marketing: true,
    preferences: true
  }));
  window.dispatchEvent(new Event('foxpixel_consent_update'));
}

// Rejeitar marketing
function acceptMinimal() {
  localStorage.setItem('foxpixel_consent', JSON.stringify({
    essential: true,
    analytics: true,
    marketing: false,
    preferences: false
  }));
  window.dispatchEvent(new Event('foxpixel_consent_update'));
}

// Verificar consentimento
function hasMarketingConsent() {
  try {
    const consent = JSON.parse(localStorage.getItem('foxpixel_consent') || '{}');
    return consent.marketing === true;
  } catch {
    return false;
  }
}

Categorias de consentimento

Categoria	Descrição	Padrão
`essential`	Funcionalidade básica	Sempre true
`analytics`	Tracking de visitantes e sessões	false
`marketing`	Pixels e conversões para plataformas de anúncios	false
`preferences`	Preferências de personalização	false

Integração com GTM

Se o Google Tag Manager está configurado no Tenant Admin, o script envia automaticamente eventos para o dataLayer:

// Evento de pageview enviado ao GTM
window.dataLayer.push({
  event: 'foxpixel_pageview',
  page_url: 'https://meusite.com/produto',
  page_title: 'Produto X'
});

// Evento custom enviado ao GTM
window.dataLayer.push({
  event: 'foxpixel_event',
  event_type: 'click',
  event_name: 'add_to_cart',
  event_data: { productId: '123' }
});

Criar triggers no GTM

No GTM, crie um trigger tipo Custom Event
Nome do evento: foxpixel_pageview ou foxpixel_event
Use variáveis do Data Layer para aceder aos dados

Performance

O script é otimizado para zero impacto na performance:

Tamanho: < 3KB gzipped
Batching: Eventos são agrupados (máx 20 ou a cada 5 segundos)
Beacon API: Envio assíncrono que não bloqueia a página
Defer: Carregamento após o DOM, não bloqueia renderização
Flush automático: Envia eventos pendentes quando o utilizador sai da página

API Reference

Endpoints públicos

Estes endpoints são usados internamente pelo script. Normalmente não precisa de os chamar diretamente.

Método	Endpoint	Descrição
POST	`/api/v1/analytics/events`	Enviar batch de eventos
POST	`/api/v1/site/consent`	Guardar consentimento
GET	`/api/v1/site/consent?visitorId=X`	Obter consentimento
GET	`/api/v1/site/tracking-config`	Obter config de tracking

Todos requerem autenticação via API Key: Authorization: Bearer sk_live_xxxxx

Troubleshooting

Os eventos não aparecem no dashboard

Verifique se o script está carregado (tab Network no DevTools)
Verifique se o consentimento foi dado (localStorage.getItem('foxpixel_consent'))
Os eventos são enviados em batch — espere até 5 segundos
Verifique se o data-site-id está correto

O visitor ID muda entre visitas

O fingerprint pode mudar se o utilizador:

Atualiza o browser
Muda a resolução do ecrã
Limpa o localStorage

Isto é esperado e é uma consequência do tracking sem cookies.

Os UTM parameters não aparecem

Verifique se os parâmetros estão na URL: https://meusite.com?utm_source=google&utm_medium=cpc&utm_campaign=springO script captura automaticamente utm_source, utm_medium, utm_campaign, utm_term e utm_content.

Tracking & Analytics

Pagamentos

Visão Geral

Instalação

O que é rastreado automaticamente

Eventos Custom

Assinatura da função

Identificação do Visitante

Aceder ao visitorId

Fluxo automático

Controlo programático

Categorias de consentimento

Integração com GTM

Criar triggers no GTM

Performance

API Reference

Endpoints públicos

Troubleshooting

​Visão Geral

​Instalação

​O que é rastreado automaticamente

​Eventos Custom

​Assinatura da função

​Identificação do Visitante

​Aceder ao visitorId

​Consentimento GDPR/LGPD

​Fluxo automático

​Controlo programático

​Categorias de consentimento

​Integração com GTM

​Criar triggers no GTM

​Performance

​API Reference

​Endpoints públicos

​Troubleshooting

Visão Geral

Instalação

O que é rastreado automaticamente

Eventos Custom

Assinatura da função

Identificação do Visitante

Aceder ao visitorId

Consentimento GDPR/LGPD

Fluxo automático

Controlo programático

Categorias de consentimento

Integração com GTM

Criar triggers no GTM

Performance

API Reference

Endpoints públicos

Troubleshooting