Documentação de Tracking e Eventos

Tudo o que precisa para instalar o ClearAnalytics no seu site e rastrear visualizações de página, eventos personalizados, objetivos de clique e transações de e-commerce.

Visão Geral

O ClearAnalytics oferece duas variantes de script de tracking. Escolha a que se adequa às suas necessidades: um script mínimo para analytics básicas de visualizações de página, ou um script completo para eventos personalizados, objetivos de clique e rastreamento de e-commerce.

Light Script (ca.js)

O script de tracking mais leve possível. Perfeito para blogs, landing pages e sites que só precisam de analytics de visualizações de página.

ca.js < 1 KB

Rastreamento automático de visualizações de página
Duração da sessão e taxa de rejeição
Captura de parâmetros de campanha UTM
Suporte para aplicações de página única

Full Script (ca-events.js)

Tudo o que está no light script, mais eventos personalizados, rastreamento de objetivos de clique, interceção do dataLayer GA4 e suporte completo de e-commerce.

ca-events.js < 2 KB

Tudo o que está no light script
Rastreamento de eventos personalizados via window.ca()
Rastreamento de objetivos de clique via data-ca-goal
Integração com dataLayer GA4
Rastreamento completo de eventos de e-commerce

Instalação

Adicione uma única tag de script ao seu site. Sem pacotes npm, sem ferramentas de build, sem ficheiros de configuração. O script carrega de forma assíncrona e não tem qualquer impacto no desempenho da página.

HTML — Light Script

Adicione isto no <head> ou no final do <body> em cada página. Rastreia automaticamente visualizações de página, duração da sessão e parâmetros UTM.

<script defer src="https://clearanalytics.eu/js/ca.js"></script>

HTML — Full Script

Use esta variante se precisar de eventos personalizados, objetivos de clique ou rastreamento de e-commerce.

<script defer src="https://clearanalytics.eu/js/ca-events.js"></script>

HTML — Full Script com DataLayer

Adicione o atributo data-ca-datalayer para intercetar automaticamente os eventos do dataLayer GA4, incluindo todos os eventos de e-commerce.

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

WordPress

Adicione a tag de script através do ficheiro functions.php do seu tema ou use um plugin de injeção de header/footer.

// functions.php
add_action('wp_head', function () {
    echo '<script defer src="https://clearanalytics.eu/js/ca-events.js"></script>';
});

React / Next.js

Use o componente Script do Next.js para carregamento ideal. O script funciona com qualquer framework React.

// app/layout.tsx  (Next.js App Router)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://clearanalytics.eu/js/ca-events.js"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Vue / Nuxt

Adicione o script através da sua configuração Nuxt ou diretamente no seu template HTML para aplicações Vue simples.

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://clearanalytics.eu/js/ca-events.js',
          defer: true,
        },
      ],
    },
  },
});

Google Tag Manager

Também pode implementar o script através do Google Tag Manager usando uma tag HTML personalizada.

Tag Type:   Custom HTML
Trigger:    All Pages

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Ao usar o GTM com o atributo data-ca-datalayer, o ClearAnalytics capturará automaticamente todos os eventos dataLayer enviados pelas suas tags GTM existentes.

Eventos Personalizados

Rastreie qualquer interação do utilizador enviando eventos personalizados com metadados opcionais. Os eventos personalizados aparecem no seu painel e podem ser usados como gatilhos de objetivos.

Requer o full script (ca-events.js).

API Signature

window.ca(eventName, properties?);

Parâmetro	Tipo	Descrição
`eventName`	string	Um nome descritivo para o evento (ex. 'signup', 'file_download').
`properties`	object	Objeto opcional com metadados adicionais. Serializado como JSON.

Exemplos

// Rastrear um registo com info do plano

window.ca('signup', { plan: 'pro' });

// Rastrear o download de um ficheiro

window.ca('file_download', {
  file_name: 'whitepaper.pdf',
  file_type: 'pdf',
});

// Rastrear a reprodução de um vídeo

window.ca('video_play', {
  video_title: 'Product Demo',
  duration: 120,
});

// Rastrear uma pesquisa interna

window.ca('search', { query: 'privacy analytics' });

Rastreamento de Objetivos de Clique

Rastreie cliques em botões e links sem escrever JavaScript. Adicione um atributo data-ca-goal a qualquer elemento HTML e o clique será registado automaticamente.

Requer o full script (ca-events.js).

Utilização

Adicione data-ca-goal="goal-name" a qualquer elemento clicável. O valor do atributo torna-se o identificador do objetivo no seu painel.

<button data-ca-goal="cta-signup">Sign Up</button>

<a href="/pricing" data-ca-goal="pricing-click">View Pricing</a>

<form data-ca-goal="contact-form-submit">
  <!-- The goal fires when any element inside is clicked -->
  <button type="submit">Send</button>
</form>

Como Funciona

O script usa delegação de eventos no documento para detetar cliques de forma eficiente:

Um evento de clique é disparado em qualquer parte da página.
O script percorre a árvore DOM para cima a partir do elemento clicado procurando um atributo data-ca-goal.
Se encontrado, envia um evento de clique com o nome do objetivo como seletor.

Visualizar Objetivos de Clique

Os eventos de objetivos de clique aparecem na página de Objetivos do seu painel. Crie um objetivo do tipo "Clique" e associe-o ao valor data-ca-goal que usou no seu HTML.

Integração com DataLayer GA4

Se o seu site já envia eventos para o dataLayer do Google Analytics, o ClearAnalytics pode intercetar esses eventos automaticamente. Este é o caminho de migração mais fácil a partir do GA4.

Requer o full script (ca-events.js).

Ativar a Interceção do DataLayer

Adicione o atributo data-ca-datalayer à tag de script. Esta abordagem opt-in garante que a funcionalidade só é ativada quando a habilita explicitamente.

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Como Funciona

Quando ativado, o script interceta todas as chamadas dataLayer.push():

Eventos de e-commerce reconhecidos (purchase, add_to_cart, etc.) são encaminhados como eventos de e-commerce.
Todos os outros eventos personalizados são encaminhados como eventos personalizados genéricos.
Eventos internos do GTM (gtm.js, gtm.dom, gtm.load, etc.) são filtrados automaticamente.
As entradas existentes do dataLayer são processadas ao carregar a página; os pushes futuros são intercetados em tempo real.

Exemplo

// These dataLayer pushes are automatically captured
dataLayer.push({
  event: 'form_submit',
  form_id: 'contact',
  form_name: 'Contact Form',
});

dataLayer.push({
  event: 'video_start',
  video_title: 'Product Demo',
  video_duration: 120,
});

Eventos Ignorados

Os seguintes eventos internos do GTM são automaticamente ignorados e não aparecerão no seu painel:

// These GTM internal events are automatically filtered out:
gtm.js, gtm.dom, gtm.load, gtm.click, gtm.linkClick, gtm.scrollDepth

Rastreamento de E-Commerce

Rastreie toda a jornada do cliente, desde a navegação de produtos até à compra e reembolso. O ClearAnalytics suporta todos os 14 eventos padrão de e-commerce usando o mesmo formato dataLayer do GA4.

Requer o full script (ca-events.js) com o atributo data-ca-datalayer.

Todos os eventos de e-commerce usam o formato dataLayer.push() compatível com GA4. Se já tem rastreamento de e-commerce do GA4 implementado, o ClearAnalytics capturará esses eventos automaticamente sem alterações de código.

Evento	Descrição
`view_item_list`	O utilizador visualiza uma lista de produtos ou resultados de pesquisa.
`select_item`	O utilizador clica num produto de uma lista.
`view_item`	O utilizador visualiza uma página de detalhe do produto.
`add_to_cart`	O utilizador adiciona um produto ao carrinho de compras.
`remove_from_cart`	O utilizador remove um produto do carrinho.
`view_cart`	O utilizador visualiza o carrinho de compras.
`add_to_wishlist`	O utilizador adiciona um produto à lista de desejos.
`begin_checkout`	O utilizador inicia o processo de checkout.
`add_shipping_info`	O utilizador submete as informações de envio.
`add_payment_info`	O utilizador submete as informações de pagamento.
`purchase`	O utilizador conclui uma compra.
`refund`	Um reembolso total ou parcial é processado.
`view_promotion`	O utilizador visualiza um banner promocional ou oferta.
`select_promotion`	O utilizador clica numa promoção.

view_item_list

Dispare este evento quando os utilizadores veem uma lista de produtos, como uma página de categoria ou resultados de pesquisa.

dataLayer.push({ ecommerce: null }); // Clear previous data
dataLayer.push({
  event: 'view_item_list',
  ecommerce: {
    item_list_id: 'category_results',
    item_list_name: 'Category Results',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Running Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        price: 89.99,
        index: 0,
      },
      {
        item_id: 'SKU-002',
        item_name: 'Trail Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        price: 119.99,
        index: 1,
      },
    ],
  },
});

select_item

Dispare este evento quando um utilizador clica num produto específico de uma lista para o visualizar.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'select_item',
  ecommerce: {
    item_list_id: 'category_results',
    item_list_name: 'Category Results',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      price: 89.99,
      index: 0,
    }],
  },
});

view_item

Dispare este evento quando um utilizador chega a uma página de detalhe do produto.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_item',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      item_category: 'Footwear',
      item_variant: 'Blue / Size 42',
      price: 89.99,
      quantity: 1,
    }],
  },
});

add_to_cart

Dispare este evento quando um utilizador adiciona um ou mais produtos ao carrinho de compras.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      price: 89.99,
      quantity: 1,
    }],
  },
});

remove_from_cart

Dispare este evento quando um utilizador remove um produto do carrinho.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'remove_from_cart',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
      quantity: 1,
    }],
  },
});

view_cart

Dispare este evento quando um utilizador visualiza a página do carrinho de compras.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_cart',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_to_wishlist

Dispare este evento quando um utilizador guarda um produto na lista de desejos para mais tarde.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_wishlist',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
    }],
  },
});

begin_checkout

Dispare este evento quando um utilizador inicia o fluxo de checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'begin_checkout',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    coupon: 'SUMMER20',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_shipping_info

Dispare este evento quando um utilizador seleciona ou submete os detalhes de envio durante o checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_shipping_info',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    shipping_tier: 'Express',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_payment_info

Dispare este evento quando um utilizador seleciona ou submete o método de pagamento durante o checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_payment_info',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    payment_type: 'Credit Card',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

purchase

Dispare este evento quando uma compra é confirmada. Inclua transaction_id, value, currency, tax, shipping e o array completo de items.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
    affiliation: 'Online Store',
    value: 209.98,
    tax: 36.49,
    shipping: 5.99,
    currency: 'EUR',
    coupon: 'SUMMER20',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Running Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        item_variant: 'Blue / Size 42',
        price: 89.99,
        quantity: 1,
        coupon: '',
      },
      {
        item_id: 'SKU-003',
        item_name: 'Sports Watch',
        item_brand: 'FitTech',
        item_category: 'Electronics',
        item_variant: 'Black',
        price: 119.99,
        quantity: 1,
        coupon: '',
      },
    ],
  },
});

refund

Dispare este evento quando um reembolso é processado. Para um reembolso total, apenas o transaction_id é necessário. Para reembolsos parciais, inclua os artigos específicos.

// Full refund
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'refund',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
  },
});

// Partial refund (specific items)
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'refund',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
    items: [{
      item_id: 'SKU-001',
      quantity: 1,
    }],
  },
});

view_promotion

Dispare este evento quando um banner promocional, carrossel ou oferta se torna visível para o utilizador.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_promotion',
  ecommerce: {
    creative_name: 'Spring Banner',
    creative_slot: 'homepage_hero',
    promotion_id: 'PROMO-SPRING-2026',
    promotion_name: 'Spring Sale 2026',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
      discount: 15.00,
    }],
  },
});

select_promotion

Dispare este evento quando um utilizador clica numa promoção para saber mais ou aproveitar a oferta.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'select_promotion',
  ecommerce: {
    creative_name: 'Spring Banner',
    creative_slot: 'homepage_hero',
    promotion_id: 'PROMO-SPRING-2026',
    promotion_name: 'Spring Sale 2026',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
    }],
  },
});

Migração do Google Analytics

O ClearAnalytics foi concebido para funcionar em paralelo ou como substituto do Google Analytics. Pode executar ambas as ferramentas em paralelo durante a migração sem conflitos.

Executar Ambos os Scripts em Paralelo

Adicione o script do ClearAnalytics ao lado da sua tag Google Analytics existente. Ambos os scripts rastreiam de forma independente sem interferir um com o outro.

<!-- Google Analytics (existing) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
</script>

<!-- ClearAnalytics (add this line) -->
<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Compatibilidade de Funcionalidades

Veja como as funcionalidades do ClearAnalytics correspondem aos seus equivalentes do Google Analytics:

Funcionalidade	Google Analytics	ClearAnalytics
Visualizações de Página	`gtag('event', 'page_view')`	Automático
Eventos Personalizados	`gtag('event', ...)`	`window.ca('event')`
E-Commerce	`dataLayer.push()`	Compatível com dataLayer
Campanhas UTM	Automático	Automático
Sessões	Baseado em cookies	Sem cookies

Passos de Migração

Adicione o script do ClearAnalytics ao seu site ao lado do Google Analytics.
Ative a interceção do dataLayer com data-ca-datalayer para capturar os eventos de e-commerce existentes.
Compare os dados em ambos os painéis durante 2-4 semanas para verificar a precisão.
Quando estiver satisfeito, remova o script do Google Analytics e desfrute de uma configuração mais rápida e focada na privacidade.

Suporte SPA

O ClearAnalytics deteta automaticamente a navegação do lado do cliente em aplicações de página única. Não é necessária configuração adicional ou integração com o router.

Como Funciona

O script interceta chamadas à API History do browser para detetar a navegação de página:

history.pushState() as chamadas são intercetadas e ativam uma nova visualização de página.
history.replaceState() as chamadas são intercetadas e ativam uma nova visualização de página.
popstate os eventos (retroceder/avançar do browser) ativam uma nova visualização de página.

Frameworks Compatíveis

Funciona imediatamente com qualquer framework que use a API History para routing:

React Next.js Vue.js Nuxt Svelte SvelteKit Angular Remix Astro Inertia.js

Não são necessários plugins de router, hooks de ciclo de vida ou chamadas de rastreamento manuais. Basta adicionar a tag de script uma vez e cada navegação de página é rastreada automaticamente.

Privacidade e Conformidade

O ClearAnalytics foi construído com a privacidade no centro. O script de tracking recolhe apenas dados anónimos e agregados. Nenhuma informação pessoal é alguma vez armazenada ou transmitida.

Sem Cookies

O script não define, lê ou depende de cookies do browser. Não é necessário banner de consentimento de cookies.

Sem Fingerprinting

Nunca criamos impressões digitais do browser. Não são usadas técnicas de fingerprinting canvas, WebGL, fontes ou áudio.

Sem Armazenamento de IP

Os endereços IP dos visitantes são usados apenas para hashing anonimizado durante o pedido. Nunca são armazenados na base de dados.

Conforme com o RGPD

Como não são recolhidos dados pessoais, o ClearAnalytics está fora do âmbito dos requisitos de consentimento do RGPD. Todos os dados permanecem na UE.

Como Anonimizamos os Visitantes

Para contar visitantes únicos sem armazenar dados pessoais, usamos um hash anónimo com rotação diária:

O endereço IP e o User-Agent do visitante são combinados com um salt de rotação diária.
Esta combinação é processada com um algoritmo SHA-256 unidirecional.
O salt roda a cada 24 horas, tornando impossível rastrear visitantes entre dias.
O endereço IP original nunca é armazenado ou registado.

Dados Recolhidos pelo Script

Os seguintes campos de dados não pessoais são enviados com cada evento de visualização de página:

Campo	Finalidade
`pathname`	O caminho URL da página visitada.
`referrer`	O URL da página de referência, se existir.
`language`	A configuração de idioma do browser.
`screen_width / screen_height`	Dimensões do ecrã para classificação do tipo de dispositivo.
`utm_*`	Parâmetros de rastreamento de campanha do URL.
`duration`	Tempo passado na página em segundos.

Como o ClearAnalytics nunca recolhe dados pessoais, não precisa de banner de consentimento de cookies, popup de privacidade ou mecanismo de opt-in para usar o nosso script de tracking. É conforme com RGPD, ePrivacy, PECR e CCPA de raiz.