Dokumentazzjoni tat-Tracking u l-Eventi

Kollox li għandek bżonn biex tinstalla ClearAnalytics fuq il-websajt tiegħek u ssegwi pageviews, eventi personalizzati, miri ta' click, u tranżazzjonijiet e-commerce.

Ħarsa Ġenerali

ClearAnalytics joffri żewġ varianti ta' skripts tat-tracking. Agħżel dik li taqbel mal-ħtiġijiet tiegħek: skript minimu għal analitika bażika tal-pageviews, jew skript sħiħ għal eventi personalizzati, miri ta' click, u tracking ta' e-commerce.

Skript Ħafif (ca.js)

L-iktar skript tat-tracking ħafif possibbli. Perfett għal blogs, landing pages, u siti li għandhom bżonn biss analitika tal-pageviews.

ca.js < 1 KB
  • Tracking awtomatiku tal-pageviews
  • Tul tas-sessjoni u rata ta' bounce
  • Qbid tal-parametri tal-kampanja UTM
  • Sapport għal applikazzjonijiet single-page

Skript Sħiħ (ca-events.js)

Kollox li hemm fl-iskript ħafif, flimkien ma' eventi personalizzati, tracking ta' miri ta' click, interċettazzjoni tal-GA4 dataLayer, u sapport sħiħ tal-e-commerce.

ca-events.js < 2 KB
  • Kollox li hemm fl-iskript ħafif
  • Tracking ta' eventi personalizzati permezz ta' window.ca()
  • Tracking ta' miri ta' click permezz ta' data-ca-goal
  • Integrazzjoni GA4 dataLayer
  • Tracking sħiħ ta' eventi e-commerce

Installazzjoni

Żid tag waħda ta' skript fuq il-websajt tiegħek. L-ebda pakketti npm, l-ebda għodod ta' build, l-ebda fajls ta' konfigurazzjoni. L-iskript jitgħabba asinkronament u m'għandu l-ebda impatt fuq il-prestazzjoni tal-paġna.

HTML — Skript Ħafif

Żid dan fil-<head> jew fl-aħħar tal-<body> f'kull paġna. Isegwi awtomatikament pageviews, tul tas-sessjoni, u parametri UTM.

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

HTML — Skript Sħiħ

Uża din il-varjant jekk għandek bżonn eventi personalizzati, miri ta' click, jew tracking ta' e-commerce.

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

HTML — Skript Sħiħ b'DataLayer

Żid l-attribut data-ca-datalayer biex awtomatikament tinterċetta l-eventi GA4 dataLayer, inklużi l-eventi kollha ta' e-commerce.

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

WordPress

Żid it-tag tal-iskript permezz tal-fajl functions.php tat-tema tiegħek jew uża plugin ta' injezzjoni header/footer.

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

React / Next.js

Uża l-komponent Script ta' Next.js għal loading ottimali. L-iskript jaħdem ma' kwalunkwe 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

Żid l-iskript permezz tal-konfigurazzjoni ta' Nuxt jew direttament fit-template HTML tiegħek għal apps Vue sempliċi.

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

Google Tag Manager

Tista' wkoll tinstalla l-iskript permezz ta' Google Tag Manager billi tuża tag Custom HTML.

Tag Type:   Custom HTML
Trigger:    All Pages

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

Meta tuża GTM bl-attribut data-ca-datalayer, ClearAnalytics awtomatikament jaqbad l-eventi kollha tal-dataLayer mibgħuta mit-tags GTM eżistenti tiegħek.

Eventi Personalizzati

Segwi kwalunkwe interazzjoni tal-utent billi tibgħat eventi personalizzati b'metadata fakultattiva. L-eventi personalizzati jidhru fid-dashboard tiegħek u jistgħu jintużaw bħala triggers ta' miri.

Jeħtieġ l-iskript sħiħ (ca-events.js).

Firma tal-API

window.ca(eventName, properties?);
Parametru Tip Deskrizzjoni
eventName string Isem deskrittiv għall-event (eż. 'signup', 'file_download').
properties object Oġġett fakultattiv b'metadata addizzjonali. Serjalizzat bħala JSON.

Eżempji

// Segwi reġistrazzjoni b'informazzjoni tal-pjan

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

// Segwi download ta' fajl

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

// Segwi play ta' vidjo

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

// Segwi tiftix intern

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

Tracking ta' Miri ta' Click

Segwi clicks fuq buttuni u links mingħajr ma tikteb JavaScript. Żid attribut data-ca-goal ma' kwalunkwe element HTML u l-click jiġi rreġistrat awtomatikament.

Jeħtieġ l-iskript sħiħ (ca-events.js).

Użu

Żid data-ca-goal="isem-il-mira" ma' kwalunkwe element li jista' jingħafas. Il-valur tal-attribut isir l-identifikatur tal-mira fid-dashboard tiegħek.

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

Kif Jaħdem

L-iskript juża delegazzjoni tal-eventi fuq id-dokument biex jidentifika clicks b'mod effiċjenti:

  1. Event ta' click jiskatta xi mkien fuq il-paġna.
  2. L-iskript jimxi 'l fuq fis-siġra DOM mill-element li ngħafas ifittex attribut data-ca-goal.
  3. Jekk jinstab, jibgħat event ta' click bl-isem tal-mira bħala selettur.

Viżwalizzazzjoni tal-Miri ta' Click

L-eventi ta' miri ta' click jidhru fil-paġna tal-Miri fid-dashboard tiegħek. Oħloq mira tat-tip "Click" u qabbilha mal-valur data-ca-goal li użajt fl-HTML tiegħek.

Integrazzjoni GA4 DataLayer

Jekk il-websajt tiegħek diġà jibgħat eventi lejn il-Google Analytics dataLayer, ClearAnalytics jista' jinterċetta dawk l-eventi awtomatikament. Din hija l-iktar triq faċli ta' migrazzjoni minn GA4.

Jeħtieġ l-iskript sħiħ (ca-events.js).

Attivazzjoni tal-Interċettazzjoni DataLayer

Żid l-attribut data-ca-datalayer mat-tag tal-iskript. Din l-approach opt-in tiżgura li l-funzjoni tiġi attivata biss meta tattivaha b'mod espliċitu.

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

Kif Jaħdem

Meta jkun attivat, l-iskript jinterċetta s-sejħiet kollha ta' dataLayer.push():

  • L-eventi e-commerce rikonoxxuti (purchase, add_to_cart, eċċ.) jiġu forwarded bħala eventi e-commerce.
  • L-eventi personalizzati l-oħra kollha jiġu forwarded bħala eventi personalizzati ġeneriċi.
  • L-eventi interni tal-GTM (gtm.js, gtm.dom, gtm.load, eċċ.) jiġu ffiltrati awtomatikament.
  • L-entrati eżistenti tad-dataLayer jiġu pproċessati mat-tagħbija tal-paġna; pushes futuri jiġu nterċettati f'ħin reali.

Eżempju

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

Eventi Injorati

L-eventi interni GTM li ġejjin jiġu injorati awtomatikament u ma jidhrux fid-dashboard tiegħek:

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

Tracking ta' E-Commerce

Segwi l-vjaġġ sħiħ tal-klijent mill-browsing tal-prodotti sal-akkwist u r-rifużjoni. ClearAnalytics jappoġġja l-14-il event standard kollha ta' e-commerce bl-istess format dataLayer bħal GA4.

Jeħtieġ l-iskript sħiħ (ca-events.js) bl-attribut data-ca-datalayer.

L-eventi kollha ta' e-commerce jużaw il-format kompatibbli GA4 dataLayer.push(). Jekk diġà għandek tracking e-commerce GA4 implimentat, ClearAnalytics jaqbad dawk l-eventi awtomatikament mingħajr l-ebda bidla fil-kodiċi.

Event Deskrizzjoni
view_item_listL-utent jara lista ta' prodotti jew riżultati tat-tiftix.
select_itemL-utent jagħfas fuq prodott f'lista.
view_itemL-utent jara paġna ta' dettalji tal-prodott.
add_to_cartL-utent iżid prodott mal-basket tax-xiri.
remove_from_cartL-utent ineħħi prodott mill-basket.
view_cartL-utent jara l-basket tax-xiri.
add_to_wishlistL-utent iżid prodott mal-wishlist tiegħu.
begin_checkoutL-utent jibda l-proċess ta' checkout.
add_shipping_infoL-utent jibgħat l-informazzjoni tal-kunsinna.
add_payment_infoL-utent jibgħat l-informazzjoni tal-ħlas.
purchaseL-utent jitlesta akkwist.
refundRifużjoni sħiħa jew parzjali tiġi pproċessata.
view_promotionL-utent jara banner jew offerta promozzjonali.
select_promotionL-utent jagħfas fuq promozzjoni.

view_item_list

Iskatta dan l-event meta l-utenti jaraw lista ta' prodotti, bħal paġna ta' kategorija jew riżultati tat-tiftix.

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

Iskatta dan l-event meta utent jagħfas fuq prodott speċifiku minn lista biex jarah.

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

Iskatta dan l-event meta utent jasal fuq paġna ta' dettalji tal-prodott.

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

Iskatta dan l-event meta utent iżid prodott wieħed jew aktar mal-basket tax-xiri.

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

Iskatta dan l-event meta utent ineħħi prodott mill-basket.

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

Iskatta dan l-event meta utent jara l-paġna tal-basket tax-xiri.

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

Iskatta dan l-event meta utent isalva prodott fil-wishlist tiegħu għal aktar tard.

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

Iskatta dan l-event meta utent jibda l-fluss ta' 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

Iskatta dan l-event meta utent jagħżel jew jibgħat id-dettalji tal-kunsinna waqt il-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

Iskatta dan l-event meta utent jagħżel jew jibgħat il-metodu tal-ħlas waqt il-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

Iskatta dan l-event meta akkwist jiġi kkonfermat. Inkludi transaction_id, value, currency, tax, shipping, u l-array sħiħ 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

Iskatta dan l-event meta rifużjoni tiġi pproċessata. Għal rifużjoni sħiħa, biss transaction_id huwa meħtieġ. Għal rifużjonijiet parzjali, inkludi l-oġġetti speċifiċi.

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

Iskatta dan l-event meta banner promozzjonali, carousel, jew offerta ssir viżibbli għall-utent.

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

Iskatta dan l-event meta utent jagħfas fuq promozzjoni biex isir jaf aktar jew jieħu vantaġġ mill-offerta.

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

Migrazzjoni minn Google Analytics

ClearAnalytics huwa ddisinjat biex jaħdem flimkien ma' jew bħala sostitut għal Google Analytics. Tista' tħaddem iż-żewġ għodod b'mod parallel matul-migrazzjoni mingħajr kunflitti.

Tħaddim taż-Żewġ Skripts b'Mod Parallel

Żid l-iskript ClearAnalytics flimkien mat-tag eżistenti ta' Google Analytics tiegħek. Iż-żewġ skripts isegwu b'mod indipendenti mingħajr ma jinterferixxu ma' xulxin.

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

Kompatibbiltà tal-Funzjonijiet

Hawn kif il-funzjonijiet ta' ClearAnalytics jikkorrispondu mal-ekwivalenti tagħhom ta' Google Analytics:

Funzjoni Google Analytics ClearAnalytics
Pageviews gtag('event', 'page_view') Awtomatiku
Eventi Personalizzati gtag('event', ...) window.ca('event')
E-Commerce dataLayer.push() kompatibbli ma' dataLayer
Kampanji UTM Awtomatiku Awtomatiku
Sessjonijiet Ibbażat fuq cookies Mingħajr cookies

Passi tal-Migrazzjoni

  1. Żid l-iskript ClearAnalytics fuq is-sit tiegħek flimkien ma' Google Analytics.
  2. Attiva l-interċettazzjoni tad-dataLayer b'data-ca-datalayer biex taqbad l-eventi e-commerce eżistenti.
  3. Qabbel id-data fiż-żewġ dashboards għal 2-4 ġimgħat biex tivverifika l-preċiżjoni.
  4. Meta tkun sodisfatt, neħħi l-iskript Google Analytics u gawdi setup iktar veloċi u orjentat lejn il-privatezza.

Sapport SPA

ClearAnalytics awtomatikament jidentifika n-navigazzjoni fuq in-naħa tal-klijent f'applikazzjonijiet single-page. L-ebda konfigurazzjoni addizzjonali jew integrazzjoni mar-router hija meħtieġa.

Kif Jaħdem

L-iskript jinterċetta s-sejħiet tal-browser History API biex jidentifika n-navigazzjoni tal-paġni:

  • history.pushState() sejħiet jiġu nterċettati u jiskataw pageview ġdida.
  • history.replaceState() sejħiet jiġu nterċettati u jiskataw pageview ġdida.
  • popstate eventi (lura/quddiem fil-browser) jiskataw pageview ġdida.

Frameworks Kompatibbli

Jaħdem mill-ewwel ma' kwalunkwe framework li juża History API għar-routing:

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

L-ebda plugins tar-router, hooks taċ-ċiklu tal-ħajja, jew sejħiet manuali tat-tracking huma meħtieġa. Żid it-tag tal-iskript darba u kull navigazzjoni tal-paġna tiġi segwita awtomatikament.

Privatezza u Konformità

ClearAnalytics huwa mibni bil-privatezza fiċ-ċentru. L-iskript tat-tracking jiġbor biss data anonima u aggregata. L-ebda informazzjoni personali qatt ma tiġi maħżuna jew trasmessa.

L-Ebda Cookies

L-iskript ma jissettjax, jaqra, jew jiddependi fuq l-ebda cookie tal-browser. L-ebda banner ta' kunsens għall-cookies huwa meħtieġ.

L-Ebda Fingerprinting

Qatt ma noħolqu fingerprints tal-browser. L-ebda tekniki ta' fingerprinting canvas, WebGL, fonts, jew audio huma użati.

L-Ebda Ħażna ta' IP

L-indirizzi IP tal-viżitaturi jintużaw biss għal hashing anonimu matul-request. Qatt ma jiġu maħżuna fid-database.

Konformi mal-GDPR

Minħabba li l-ebda data personali tinġabar, ClearAnalytics jaqa' barra mill-ambitu tar-rekwiżiti ta' kunsens tal-GDPR. Id-data kollha tibqa' fl-UE.

Kif Nanonimizzaw il-Viżitaturi

Biex ngħoddu viżitaturi uniċi mingħajr ma naħżnu data personali, nużaw hash anonimu b'rotazzjoni ta' kuljum:

  • L-indirizz IP tal-viżitatur u l-User-Agent jiġu kkombinati ma' salt b'rotazzjoni ta' kuljum.
  • Din il-kombinazzjoni tiġi hashed permezz ta' algoritmu SHA-256 unidirezzjonali.
  • Is-salt jirrotat kull 24 siegħa, u jagħmilha impossibbli li ssegwi viżitaturi bejn il-jiem.
  • L-indirizz IP oriġinali qatt ma jiġi maħżun jew irreġistrat.

Data Miġbura mill-Iskript

Il-fields ta' data non-personali li ġejjin jiġu mibgħuta ma' kull event ta' pageview:

Field Skop
pathnameIl-path tal-URL tal-paġna viżitata.
referrerIl-URL tal-paġna ta' referenza, jekk hemm.
languageIs-setting tal-lingwa tal-browser.
screen_width / screen_heightId-dimensjonijiet tal-iskrin għall-klassifikazzjoni tat-tip ta' apparat.
utm_*Il-parametri tat-tracking tal-kampanja mill-URL.
durationIl-ħin li nqeda fuq il-paġna f'sekondi.

Minħabba li ClearAnalytics qatt ma jiġbor data personali, m'għandekx bżonn banner ta' kunsens għall-cookies, popup ta' privatezza, jew mekkaniżmu opt-in biex tuża l-iskript tat-tracking tagħna. Huwa konformi mal-GDPR, ePrivacy, PECR, u CCPA mill-ewwel.