Dokumentacja śledzenia i zdarzeń

Wszystko, czego potrzebujesz, aby zainstalować ClearAnalytics na swojej stronie i śledzić odsłony, zdarzenia niestandardowe, cele kliknięć i transakcje e-commerce.

Przegląd

ClearAnalytics oferuje dwa warianty skryptu śledzącego. Wybierz ten, który odpowiada Twoim potrzebom: minimalny skrypt do podstawowej analityki odsłon lub pełnofunkcyjny skrypt do zdarzeń niestandardowych, celów kliknięć i śledzenia e-commerce.

Lekki skrypt (ca.js)

Najlżejszy możliwy skrypt śledzący. Idealny dla blogów, stron docelowych i witryn, które potrzebują tylko analityki odsłon.

ca.js < 1 KB

Automatyczne śledzenie odsłon
Czas sesji i współczynnik odrzuceń
Przechwytywanie parametrów kampanii UTM
Wsparcie dla aplikacji jednostronicowych

Pełny skrypt (ca-events.js)

Wszystko z lekkiego skryptu plus zdarzenia niestandardowe, śledzenie celów kliknięć, przechwytywanie GA4 dataLayer i pełne wsparcie e-commerce.

ca-events.js < 2 KB

Wszystko z lekkiego skryptu
Śledzenie zdarzeń niestandardowych przez window.ca()
Śledzenie celów kliknięć przez data-ca-goal
Integracja z GA4 dataLayer
Pełne śledzenie zdarzeń e-commerce

Instalacja

Dodaj pojedynczy tag skryptu do swojej strony. Bez pakietów npm, bez narzędzi budowania, bez plików konfiguracyjnych. Skrypt ładuje się asynchronicznie i nie ma wpływu na wydajność strony.

HTML — Lekki skrypt

Dodaj to do sekcji <head> lub na końcu <body> na każdej stronie. Automatycznie śledzi odsłony, czas sesji i parametry UTM.

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

HTML — Pełny skrypt

Użyj tego wariantu, jeśli potrzebujesz zdarzeń niestandardowych, celów kliknięć lub śledzenia e-commerce.

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

HTML — Pełny skrypt z DataLayer

Dodaj atrybut data-ca-datalayer, aby automatycznie przechwytywać zdarzenia GA4 dataLayer, w tym wszystkie zdarzenia e-commerce.

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

WordPress

Dodaj tag skryptu przez plik functions.php motywu lub użyj wtyczki do wstrzykiwania nagłówka/stopki.

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

React / Next.js

Użyj komponentu Script z Next.js do optymalnego ładowania. Skrypt działa z dowolnym frameworkiem 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

Dodaj skrypt przez konfigurację Nuxt lub bezpośrednio w szablonie HTML dla zwykłych aplikacji Vue.

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

Google Tag Manager

Możesz również wdrożyć skrypt przez Google Tag Manager, używając niestandardowego tagu HTML.

Tag Type:   Custom HTML
Trigger:    All Pages

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

Przy użyciu GTM z atrybutem data-ca-datalayer, ClearAnalytics automatycznie przechwyci wszystkie zdarzenia dataLayer wysyłane przez istniejące tagi GTM.

Zdarzenia niestandardowe

Śledź dowolną interakcję użytkownika, wysyłając zdarzenia niestandardowe z opcjonalnymi metadanymi. Zdarzenia niestandardowe pojawiają się w panelu i mogą być używane jako wyzwalacze celów.

Wymaga pełnego skryptu (ca-events.js).

Sygnatura API

window.ca(eventName, properties?);

Parametr	Typ	Opis
`eventName`	string	Opisowa nazwa zdarzenia (np. 'signup', 'file_download').
`properties`	object	Opcjonalny obiekt z dodatkowymi metadanymi. Serializowany jako JSON.

Przykłady

// Śledź rejestrację z informacją o planie

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

// Śledź pobranie pliku

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

// Śledź odtworzenie wideo

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

// Śledź wyszukiwanie wewnętrzne

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

Śledzenie celów kliknięć

Śledź kliknięcia przycisków i linków bez pisania kodu JavaScript. Dodaj atrybut data-ca-goal do dowolnego elementu HTML, a kliknięcie zostanie automatycznie zarejestrowane.

Wymaga pełnego skryptu (ca-events.js).

Użycie

Dodaj data-ca-goal="nazwa-celu" do dowolnego klikalnego elementu. Wartość atrybutu staje się identyfikatorem celu w panelu.

<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>

Jak to działa

Skrypt wykorzystuje delegowanie zdarzeń na dokumencie, aby efektywnie wykrywać kliknięcia:

Zdarzenie kliknięcia zachodzi w dowolnym miejscu na stronie.
Skrypt przechodzi w górę drzewa DOM od klikniętego elementu, szukając atrybutu data-ca-goal.
Jeśli zostanie znaleziony, wysyła zdarzenie kliknięcia z nazwą celu jako selektorem.

Przeglądanie celów kliknięć

Zdarzenia celów kliknięć pojawiają się na stronie Cele w panelu. Utwórz cel typu "Kliknięcie" i dopasuj go do wartości data-ca-goal użytej w HTML.

Integracja z GA4 DataLayer

Jeśli Twoja strona już wysyła zdarzenia do Google Analytics dataLayer, ClearAnalytics może automatycznie przechwytywać te zdarzenia. To najłatwiejsza ścieżka migracji z GA4.

Wymaga pełnego skryptu (ca-events.js).

Włączanie przechwytywania DataLayer

Dodaj atrybut data-ca-datalayer do tagu skryptu. To podejście opt-in zapewnia, że funkcja aktywuje się tylko wtedy, gdy wyraźnie ją włączysz.

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

Jak to działa

Po włączeniu skrypt przechwytuje wszystkie wywołania dataLayer.push():

Rozpoznane zdarzenia e-commerce (purchase, add_to_cart itp.) są przekazywane jako zdarzenia e-commerce.
Wszystkie inne zdarzenia niestandardowe są przekazywane jako ogólne zdarzenia niestandardowe.
Wewnętrzne zdarzenia GTM (gtm.js, gtm.dom, gtm.load itp.) są automatycznie odfiltrowywane.
Istniejące wpisy dataLayer są przetwarzane przy ładowaniu strony; przyszłe wywołania push są przechwytywane w czasie rzeczywistym.

Przykład

// 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,
});

Ignorowane zdarzenia

Następujące wewnętrzne zdarzenia GTM są automatycznie ignorowane i nie pojawią się w Twoim panelu:

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

Śledzenie e-commerce

Śledź pełną ścieżkę klienta od przeglądania produktów po zakup i zwrot. ClearAnalytics obsługuje wszystkie 14 standardowych zdarzeń e-commerce, używając tego samego formatu dataLayer co GA4.

Wymaga pełnego skryptu (ca-events.js) z atrybutem data-ca-datalayer.

Wszystkie zdarzenia e-commerce używają formatu dataLayer.push() kompatybilnego z GA4. Jeśli masz już wdrożone śledzenie e-commerce GA4, ClearAnalytics przechwyci te zdarzenia automatycznie bez zmian w kodzie.

Zdarzenie	Opis
`view_item_list`	Użytkownik widzi listę produktów lub wyniki wyszukiwania.
`select_item`	Użytkownik klika produkt na liście.
`view_item`	Użytkownik ogląda stronę szczegółów produktu.
`add_to_cart`	Użytkownik dodaje produkt do koszyka.
`remove_from_cart`	Użytkownik usuwa produkt z koszyka.
`view_cart`	Użytkownik ogląda koszyk.
`add_to_wishlist`	Użytkownik dodaje produkt do listy życzeń.
`begin_checkout`	Użytkownik rozpoczyna proces zamówienia.
`add_shipping_info`	Użytkownik przesyła informacje o dostawie.
`add_payment_info`	Użytkownik przesyła informacje o płatności.
`purchase`	Użytkownik finalizuje zakup.
`refund`	Przetwarzany jest pełny lub częściowy zwrot.
`view_promotion`	Użytkownik widzi baner promocyjny lub ofertę.
`select_promotion`	Użytkownik klika promocję.

view_item_list

Wywołaj to zdarzenie, gdy użytkownicy widzą listę produktów, np. stronę kategorii lub wyniki wyszukiwania.

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

Wywołaj to zdarzenie, gdy użytkownik klika konkretny produkt z listy, aby go zobaczyć.

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

Wywołaj to zdarzenie, gdy użytkownik trafia na stronę szczegółów produktu.

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

Wywołaj to zdarzenie, gdy użytkownik dodaje jeden lub więcej produktów do koszyka.

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

Wywołaj to zdarzenie, gdy użytkownik usuwa produkt z koszyka.

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

Wywołaj to zdarzenie, gdy użytkownik przegląda stronę koszyka.

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

Wywołaj to zdarzenie, gdy użytkownik zapisuje produkt na liście życzeń na później.

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

Wywołaj to zdarzenie, gdy użytkownik rozpoczyna proces zamówienia.

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

Wywołaj to zdarzenie, gdy użytkownik wybiera lub przesyła dane dostawy podczas zamówienia.

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

Wywołaj to zdarzenie, gdy użytkownik wybiera lub przesyła metodę płatności podczas zamówienia.

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

Wywołaj to zdarzenie, gdy zakup zostanie potwierdzony. Dołącz transaction_id, value, currency, tax, shipping i pełną tablicę 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

Wywołaj to zdarzenie, gdy przetwarzany jest zwrot. Dla pełnego zwrotu wystarczy transaction_id. Dla częściowych zwrotów dołącz konkretne produkty.

// 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

Wywołaj to zdarzenie, gdy baner promocyjny, karuzela lub oferta staje się widoczna dla użytkownika.

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

Wywołaj to zdarzenie, gdy użytkownik klika promocję, aby dowiedzieć się więcej lub skorzystać z oferty.

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,
    }],
  },
});

Migracja z Google Analytics

ClearAnalytics jest zaprojektowany do pracy równolegle z Google Analytics lub jako jego zamiennik. Możesz używać obu narzędzi jednocześnie podczas migracji bez konfliktów.

Uruchamianie obu skryptów równolegle

Dodaj skrypt ClearAnalytics obok istniejącego tagu Google Analytics. Oba skrypty będą śledzić niezależnie, nie zakłócając się nawzajem.

<!-- 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>

Kompatybilność funkcji

Oto jak funkcje ClearAnalytics odpowiadają ich odpowiednikom w Google Analytics:

Funkcja	Google Analytics	ClearAnalytics
Odsłony	`gtag('event', 'page_view')`	Automatycznie
Zdarzenia niestandardowe	`gtag('event', ...)`	`window.ca('event')`
E-Commerce	`dataLayer.push()`	kompatybilny z dataLayer
Kampanie UTM	Automatycznie	Automatycznie
Sesje	Na bazie ciasteczek	Bez ciasteczek

Kroki migracji

Dodaj skrypt ClearAnalytics na swojej stronie obok Google Analytics.
Włącz przechwytywanie dataLayer za pomocą data-ca-datalayer, aby przechwytywać istniejące zdarzenia e-commerce.
Porównuj dane w obu panelach przez 2-4 tygodnie, aby zweryfikować dokładność.
Gdy będziesz zadowolony, usuń skrypt Google Analytics i ciesz się szybszą konfiguracją zorientowaną na prywatność.

Wsparcie SPA

ClearAnalytics automatycznie wykrywa nawigację po stronie klienta w aplikacjach jednostronicowych. Nie jest wymagana dodatkowa konfiguracja ani integracja z routerem.

Jak to działa

Skrypt przechwytuje wywołania History API przeglądarki w celu wykrycia nawigacji po stronach:

history.pushState() wywołania są przechwytywane i wyzwalają nową odsłonę.
history.replaceState() wywołania są przechwytywane i wyzwalają nową odsłonę.
popstate zdarzenia (przycisk wstecz/dalej przeglądarki) wyzwalają nową odsłonę.

Kompatybilne frameworki

Działa od razu z dowolnym frameworkiem, który wykorzystuje History API do routingu:

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

Nie potrzeba wtyczek routera, hooków cyklu życia ani ręcznych wywołań śledzenia. Wystarczy dodać tag skryptu raz, a każda nawigacja po stronie będzie śledzona automatycznie.

Prywatność i zgodność

ClearAnalytics jest zbudowany z prywatnością w swoim rdzeniu. Skrypt śledzący zbiera wyłącznie anonimowe, zagregowane dane. Żadne dane osobowe nie są kiedykolwiek przechowywane ani przesyłane.

Bez ciasteczek

Skrypt nie ustawia, nie odczytuje ani nie zależy od żadnych ciasteczek przeglądarki. Baner zgody na ciasteczka nie jest potrzebny.

Bez fingerprintingu

Nigdy nie tworzymy odcisków palców przeglądarki. Nie stosujemy technik fingerprintingu canvas, WebGL, czcionek ani audio.

Bez przechowywania IP

Adresy IP odwiedzających są używane wyłącznie do anonimizowanego hashowania podczas żądania. Nigdy nie są przechowywane w bazie danych.

Zgodny z GDPR

Ponieważ nie zbieramy danych osobowych, ClearAnalytics nie podlega wymogom zgody GDPR. Wszystkie dane pozostają w UE.

Jak anonimizujemy odwiedzających

Aby liczyć unikalnych odwiedzających bez przechowywania danych osobowych, używamy codziennie rotowanego anonimowego hashu:

Adres IP odwiedzającego i User-Agent są łączone z codziennie rotowaną solą.
Ta kombinacja jest hashowana za pomocą jednokierunkowego algorytmu SHA-256.
Sól zmienia się co 24 godziny, co uniemożliwia śledzenie odwiedzających między dniami.
Oryginalny adres IP nigdy nie jest przechowywany ani logowany.

Dane zbierane przez skrypt

Następujące nieosobowe pola danych są wysyłane z każdym zdarzeniem odsłony:

Pole	Cel
`pathname`	Ścieżka URL odwiedzanej strony.
`referrer`	URL strony odsyłającej, jeśli istnieje.
`language`	Ustawienie języka przeglądarki.
`screen_width / screen_height`	Wymiary ekranu do klasyfikacji typu urządzenia.
`utm_*`	Parametry śledzenia kampanii z URL.
`duration`	Czas spędzony na stronie w sekundach.

Ponieważ ClearAnalytics nigdy nie zbiera danych osobowych, nie potrzebujesz baneru zgody na ciasteczka, wyskakującego okna prywatności ani mechanizmu opt-in, aby korzystać z naszego skryptu śledzącego. Jest zgodny z GDPR, ePrivacy, PECR i CCPA od razu po instalacji.