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:
- Event ta' click jiskatta xi mkien fuq il-paġna.
- L-iskript jimxi 'l fuq fis-siġra DOM mill-element li ngħafas ifittex attribut data-ca-goal.
- 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_list | L-utent jara lista ta' prodotti jew riżultati tat-tiftix. |
select_item | L-utent jagħfas fuq prodott f'lista. |
view_item | L-utent jara paġna ta' dettalji tal-prodott. |
add_to_cart | L-utent iżid prodott mal-basket tax-xiri. |
remove_from_cart | L-utent ineħħi prodott mill-basket. |
view_cart | L-utent jara l-basket tax-xiri. |
add_to_wishlist | L-utent iżid prodott mal-wishlist tiegħu. |
begin_checkout | L-utent jibda l-proċess ta' checkout. |
add_shipping_info | L-utent jibgħat l-informazzjoni tal-kunsinna. |
add_payment_info | L-utent jibgħat l-informazzjoni tal-ħlas. |
purchase | L-utent jitlesta akkwist. |
refund | Rifużjoni sħiħa jew parzjali tiġi pproċessata. |
view_promotion | L-utent jara banner jew offerta promozzjonali. |
select_promotion | L-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
- Żid l-iskript ClearAnalytics fuq is-sit tiegħek flimkien ma' Google Analytics.
- Attiva l-interċettazzjoni tad-dataLayer b'data-ca-datalayer biex taqbad l-eventi e-commerce eżistenti.
- Qabbel id-data fiż-żewġ dashboards għal 2-4 ġimgħat biex tivverifika l-preċiżjoni.
- 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. -
popstateeventi (lura/quddiem fil-browser) jiskataw pageview ġdida.
Frameworks Kompatibbli
Jaħdem mill-ewwel ma' kwalunkwe framework li juża History API għar-routing:
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 |
|---|---|
pathname | Il-path tal-URL tal-paġna viżitata. |
referrer | Il-URL tal-paġna ta' referenza, jekk hemm. |
language | Is-setting tal-lingwa tal-browser. |
screen_width / screen_height | Id-dimensjonijiet tal-iskrin għall-klassifikazzjoni tat-tip ta' apparat. |
utm_* | Il-parametri tat-tracking tal-kampanja mill-URL. |
duration | Il-ħ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.