Skip to main content

​
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

EventoQuandoDados recolhidos
PageviewCada carregamento de páginaURL, título, referrer, UTM params
Navegação SPAMudança de rota (pushState/replaceState)Nova URL, título anterior, título novo
Dados do dispositivoEm cada eventoTipo (desktop/mobile/tablet), browser, OS, resolução
UTM ParametersSe presentes na URLsource, 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:
StorageChaveDuraçãoConteúdo
localStorage_fp_vidPermanenteHash FNV-1a (canvas + UA + screen + timezone)
sessionStorage_fp_sidAté fechar o tabUUID 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.

​
Consentimento GDPR/LGPD

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

​
Fluxo automático

  1. Se o banner GDPR está ativado no Tenant Admin, o script espera pelo consentimento
  2. Quando o utilizador aceita, o consentimento é guardado em localStorage
  3. 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

CategoriaDescriçãoPadrão
essentialFuncionalidade básicaSempre true
analyticsTracking de visitantes e sessõesfalse
marketingPixels e conversões para plataformas de anúnciosfalse
preferencesPreferências de personalizaçãofalse

​
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

  1. No GTM, crie um trigger tipo Custom Event
  2. Nome do evento: foxpixel_pageview ou foxpixel_event
  3. 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étodoEndpointDescrição
POST/api/v1/analytics/eventsEnviar batch de eventos
POST/api/v1/site/consentGuardar consentimento
GET/api/v1/site/consent?visitorId=XObter consentimento
GET/api/v1/site/tracking-configObter config de tracking
Todos requerem autenticação via API Key: Authorization: Bearer sk_live_xxxxx

​
Troubleshooting

  1. Verifique se o script está carregado (tab Network no DevTools)
  2. Verifique se o consentimento foi dado (localStorage.getItem('foxpixel_consent'))
  3. Os eventos são enviados em batch — espere até 5 segundos
  4. Verifique se o data-site-id está correto
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.
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.