Tracking & Events Documentation

Everything you need to install ClearAnalytics on your website and track pageviews, custom events, click goals, and e-commerce transactions.

Overview

ClearAnalytics offers two tracking script variants. Choose the one that fits your needs: a minimal script for basic pageview analytics, or a full-featured script for custom events, click goals, and e-commerce tracking.

Light Script (ca.js)

The lightest possible tracking script. Perfect for blogs, landing pages, and sites that only need pageview analytics.

ca.js < 1 KB

Automatic pageview tracking
Session duration and bounce rate
UTM campaign parameter capture
Single-page application support

Full Script (ca-events.js)

Everything in the light script, plus custom events, click goal tracking, GA4 dataLayer interception, and full e-commerce support.

ca-events.js < 2 KB

Everything in the light script
Custom event tracking via window.ca()
Click goal tracking via data-ca-goal
GA4 dataLayer integration
Full e-commerce event tracking

Installation

Add a single script tag to your website. No npm packages, no build tools, no configuration files. The script loads asynchronously and has zero impact on page performance.

HTML — Light Script

Add this to the <head> or end of <body> on every page. Tracks pageviews, session duration, and UTM parameters automatically.

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

HTML — Full Script

Use this variant if you need custom events, click goals, or e-commerce tracking.

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

HTML — Full Script with DataLayer

Add the data-ca-datalayer attribute to automatically intercept GA4 dataLayer events, including all e-commerce events.

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

WordPress

Add the script tag via your theme's functions.php file or use a header/footer injection plugin.

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

React / Next.js

Use the Next.js Script component for optimal loading. The script works with any React framework.

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

Add the script via your Nuxt configuration or directly in your HTML template for plain Vue apps.

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

Google Tag Manager

You can also deploy the script through Google Tag Manager using a Custom HTML tag.

Tag Type:   Custom HTML
Trigger:    All Pages

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

When using GTM with the data-ca-datalayer attribute, ClearAnalytics will automatically capture all dataLayer events pushed by your existing GTM tags.

Custom Events

Track any user interaction by sending custom events with optional metadata. Custom events appear in your dashboard and can be used as goal triggers.

Requires the full script (ca-events.js).

API Signature

window.ca(eventName, properties?);

Parameter	Type	Description
`eventName`	string	A descriptive name for the event (e.g. 'signup', 'file_download').
`properties`	object	Optional object with additional metadata. Serialized as JSON.

Examples

// Track a signup with plan info

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

// Track a file download

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

// Track a video play

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

// Track an internal search

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

Click Goal Tracking

Track button and link clicks without writing any JavaScript. Add a data-ca-goal attribute to any HTML element and the click will be recorded automatically.

Requires the full script (ca-events.js).

Usage

Add data-ca-goal="goal-name" to any clickable element. The attribute value becomes the goal identifier in your dashboard.

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

How It Works

The script uses event delegation on the document to detect clicks efficiently:

A click event fires anywhere on the page.
The script walks up the DOM tree from the clicked element looking for a data-ca-goal attribute.
If found, it sends a click event with the goal name as the selector.

Viewing Click Goals

Click goal events appear on the Goals page in your dashboard. Create a goal with type "Click" and match it to the data-ca-goal value you used in your HTML.

GA4 DataLayer Integration

If your site already pushes events to the Google Analytics dataLayer, ClearAnalytics can intercept those events automatically. This is the easiest migration path from GA4.

Requires the full script (ca-events.js).

Enabling DataLayer Interception

Add the data-ca-datalayer attribute to the script tag. This opt-in approach ensures the feature only activates when you explicitly enable it.

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

How It Works

When enabled, the script intercepts all dataLayer.push() calls:

Recognized e-commerce events (purchase, add_to_cart, etc.) are forwarded as e-commerce events.
All other custom events are forwarded as generic custom events.
Internal GTM events (gtm.js, gtm.dom, gtm.load, etc.) are automatically filtered out.
Existing dataLayer entries are processed on page load; future pushes are intercepted in real-time.

Example

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

Ignored Events

The following GTM internal events are automatically ignored and will not appear in your dashboard:

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

E-Commerce Tracking

Track the full customer journey from product browsing to purchase and refund. ClearAnalytics supports all 14 standard e-commerce events using the same dataLayer format as GA4.

Requires the full script (ca-events.js) with the data-ca-datalayer attribute.

All e-commerce events use the GA4-compatible dataLayer.push() format. If you already have GA4 e-commerce tracking implemented, ClearAnalytics will capture those events automatically with zero code changes.

Event	Description
`view_item_list`	User views a list of products or search results.
`select_item`	User clicks on a product in a list.
`view_item`	User views a product detail page.
`add_to_cart`	User adds a product to the shopping cart.
`remove_from_cart`	User removes a product from the cart.
`view_cart`	User views the shopping cart.
`add_to_wishlist`	User adds a product to their wishlist.
`begin_checkout`	User starts the checkout process.
`add_shipping_info`	User submits their shipping information.
`add_payment_info`	User submits their payment information.
`purchase`	User completes a purchase.
`refund`	A full or partial refund is processed.
`view_promotion`	User views a promotional banner or offer.
`select_promotion`	User clicks on a promotion.

view_item_list

Fire this event when users see a list of products, such as a category page or search results.

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

Fire this event when a user clicks on a specific product from a list to view it.

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

Fire this event when a user lands on a product detail page.

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

Fire this event when a user adds one or more products to their shopping cart.

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

Fire this event when a user removes a product from their cart.

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

Fire this event when a user views their shopping cart page.

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

Fire this event when a user saves a product to their wishlist for later.

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

Fire this event when a user starts the checkout flow.

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

Fire this event when a user selects or submits their shipping details during 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

Fire this event when a user selects or submits their payment method during 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

Fire this event when a purchase is confirmed. Include transaction_id, value, currency, tax, shipping, and the full items array.

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

Fire this event when a refund is processed. For a full refund, only the transaction_id is required. For partial refunds, include the specific items.

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

Fire this event when a promotional banner, carousel, or offer becomes visible to the user.

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

Fire this event when a user clicks on a promotion to learn more or take advantage of the offer.

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

Migrating from Google Analytics

ClearAnalytics is designed to work alongside or as a replacement for Google Analytics. You can run both tools in parallel during migration with no conflicts.

Running Both Scripts in Parallel

Add the ClearAnalytics script alongside your existing Google Analytics tag. Both scripts will track independently without interfering with each other.

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

Feature Compatibility

Here is how ClearAnalytics features map to their Google Analytics equivalents:

Feature	Google Analytics	ClearAnalytics
Pageviews	`gtag('event', 'page_view')`	Automatic
Custom Events	`gtag('event', ...)`	`window.ca('event')`
E-Commerce	`dataLayer.push()`	dataLayer compatible
UTM Campaigns	Automatic	Automatic
Sessions	Cookie-based	Cookie-free

Migration Steps

Add the ClearAnalytics script to your site alongside Google Analytics.
Enable dataLayer interception with data-ca-datalayer to capture existing e-commerce events.
Compare data in both dashboards for 2-4 weeks to verify accuracy.
Once satisfied, remove the Google Analytics script and enjoy a faster, privacy-first setup.

SPA Support

ClearAnalytics automatically detects client-side navigation in single-page applications. No additional configuration or router integration is required.

How It Works

The script intercepts browser History API calls to detect page navigation:

history.pushState() calls are intercepted and trigger a new pageview.
history.replaceState() calls are intercepted and trigger a new pageview.
popstate events (browser back/forward) trigger a new pageview.

Compatible Frameworks

Works out of the box with any framework that uses the History API for routing:

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

No router plugins, lifecycle hooks, or manual tracking calls are needed. Just add the script tag once and every page navigation is tracked automatically.

Privacy & Compliance

ClearAnalytics is built with privacy at its core. The tracking script collects only anonymous, aggregated data. No personal information is ever stored or transmitted.

No Cookies

The script does not set, read, or depend on any browser cookies. No cookie consent banner is needed.

No Fingerprinting

We never create browser fingerprints. No canvas, WebGL, font, or audio fingerprinting techniques are used.

No IP Storage

Visitor IP addresses are used only for anonymized hashing during the request. They are never stored in the database.

GDPR Compliant

Because no personal data is collected, ClearAnalytics falls outside the scope of GDPR consent requirements. All data stays in the EU.

How We Anonymize Visitors

To count unique visitors without storing personal data, we use a daily-rotating anonymous hash:

The visitor's IP address and User-Agent are combined with a daily-rotating salt.
This combination is hashed using a one-way SHA-256 algorithm.
The salt rotates every 24 hours, making it impossible to track visitors across days.
The original IP address is never stored or logged.

Data Collected by the Script

The following non-personal data fields are sent with each pageview event:

Field	Purpose
`pathname`	The page URL path being visited.
`referrer`	The referring page URL, if any.
`language`	The browser's language setting.
`screen_width / screen_height`	Screen dimensions for device type classification.
`utm_*`	Campaign tracking parameters from the URL.
`duration`	Time spent on the page in seconds.

Because ClearAnalytics never collects personal data, you do not need a cookie consent banner, privacy popup, or opt-in mechanism to use our tracking script. It is compliant with GDPR, ePrivacy, PECR, and CCPA out of the box.