Документация за проследяване и събития

Всичко необходимо за инсталиране на ClearAnalytics на вашия уебсайт и проследяване на прегледи на страници, персонализирани събития, цели за кликвания и транзакции в електронната търговия.

Общ преглед

ClearAnalytics предлага два варианта на скрипт за проследяване. Изберете този, който отговаря на вашите нужди: минимален скрипт за основна аналитика на прегледи на страници или пълнофункционален скрипт за персонализирани събития, цели за кликвания и проследяване на електронна търговия.

Лек скрипт (ca.js)

Най-лекият възможен скрипт за проследяване. Перфектен за блогове, целеви страници и сайтове, които се нуждаят само от аналитика на прегледи на страници.

ca.js < 1 KB

Автоматично проследяване на прегледи на страници
Продължителност на сесия и процент на отказване
Улавяне на UTM параметри на кампании
Поддръжка на едностранични приложения

Пълен скрипт (ca-events.js)

Всичко от лекия скрипт, плюс персонализирани събития, проследяване на цели за кликвания, прихващане на GA4 dataLayer и пълна поддръжка на електронна търговия.

ca-events.js < 2 KB

Всичко от лекия скрипт
Проследяване на персонализирани събития чрез window.ca()
Проследяване на цели за кликвания чрез data-ca-goal
Интеграция с GA4 dataLayer
Пълно проследяване на събития в електронната търговия

Инсталация

Добавете един script таг към вашия уебсайт. Без npm пакети, без инструменти за изграждане, без конфигурационни файлове. Скриптът се зарежда асинхронно и няма никакво влияние върху производителността на страницата.

HTML — Лек скрипт

Добавете това в <head> или в края на <body> на всяка страница. Автоматично проследява прегледи на страници, продължителност на сесия и UTM параметри.

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

HTML — Пълен скрипт

Използвайте този вариант, ако имате нужда от персонализирани събития, цели за кликвания или проследяване на електронна търговия.

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

HTML — Пълен скрипт с DataLayer

Добавете атрибута data-ca-datalayer за автоматично прихващане на GA4 dataLayer събития, включително всички събития на електронната търговия.

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

WordPress

Добавете script тага чрез файла functions.php на вашата тема или използвайте плъгин за вмъкване в хедъра/футъра.

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

React / Next.js

Използвайте компонента Script на Next.js за оптимално зареждане. Скриптът работи с всяка 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

Добавете скрипта чрез Nuxt конфигурацията или директно във вашия HTML шаблон за обикновени Vue приложения.

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

Google Tag Manager

Можете също да разгърнете скрипта чрез Google Tag Manager, използвайки персонализиран HTML таг.

Tag Type:   Custom HTML
Trigger:    All Pages

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

Когато използвате GTM с атрибута data-ca-datalayer, ClearAnalytics автоматично ще улавя всички dataLayer събития, изпратени от вашите съществуващи GTM тагове.

Персонализирани събития

Проследявайте всяко взаимодействие на потребителя чрез изпращане на персонализирани събития с незадължителни метаданни. Персонализираните събития се показват на вашето табло и могат да се използват като тригери за цели.

Изисква пълния скрипт (ca-events.js).

API сигнатура

window.ca(eventName, properties?);

Параметър	Тип	Описание
`eventName`	string	Описателно име за събитието (напр. 'signup', 'file_download').
`properties`	object	Незадължителен обект с допълнителни метаданни. Сериализиран като JSON.

Примери

// Проследяване на регистрация с информация за план

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

// Проследяване на изтегляне на файл

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

// Проследяване на възпроизвеждане на видео

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

// Проследяване на вътрешно търсене

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

Проследяване на цели за кликвания

Проследявайте кликвания върху бутони и връзки без писане на JavaScript. Добавете атрибут data-ca-goal към всеки HTML елемент и кликването ще бъде записано автоматично.

Изисква пълния скрипт (ca-events.js).

Употреба

Добавете data-ca-goal="име-на-цел" към всеки кликаем елемент. Стойността на атрибута става идентификатор на целта на вашето табло.

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

Как работи

Скриптът използва делегиране на събития върху документа за ефективно откриване на кликвания:

Събитие за кликване се задейства някъде на страницата.
Скриптът обхожда DOM дървото от кликнатия елемент, търсейки атрибут data-ca-goal.
Ако бъде намерен, изпраща събитие за кликване с името на целта като селектор.

Преглед на цели за кликвания

Събитията за цели за кликвания се показват на страницата Цели на вашето табло. Създайте цел с тип "Кликване" и я свържете със стойността data-ca-goal, използвана във вашия HTML.

Интеграция с GA4 DataLayer

Ако вашият сайт вече изпраща събития към Google Analytics dataLayer, ClearAnalytics може автоматично да прихване тези събития. Това е най-лесният път за миграция от GA4.

Изисква пълния скрипт (ca-events.js).

Активиране на прихващането на DataLayer

Добавете атрибута data-ca-datalayer към script тага. Този подход за включване гарантира, че функцията се активира само когато изрично я разрешите.

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

Как работи

Когато е активирано, скриптът прихваща всички dataLayer.push() извиквания:

Разпознатите събития на електронната търговия (purchase, add_to_cart и др.) се препращат като събития на електронната търговия.
Всички други персонализирани събития се препращат като общи персонализирани събития.
Вътрешните GTM събития (gtm.js, gtm.dom, gtm.load и др.) автоматично се филтрират.
Съществуващите записи в dataLayer се обработват при зареждане на страницата; бъдещите push-ове се прихващат в реално време.

Пример

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

Игнорирани събития

Следните вътрешни GTM събития автоматично се игнорират и няма да се показват на вашето табло:

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

Проследяване на електронна търговия

Проследявайте целия път на клиента от разглеждане на продукти до покупка и възстановяване. ClearAnalytics поддържа всичките 14 стандартни събития за електронна търговия, използвайки същия dataLayer формат като GA4.

Изисква пълния скрипт (ca-events.js) с атрибута data-ca-datalayer.

Всички събития на електронната търговия използват GA4-съвместимия dataLayer.push() формат. Ако вече имате внедрено GA4 проследяване на електронна търговия, ClearAnalytics автоматично ще улавя тези събития без промени в кода.

Събитие	Описание
`view_item_list`	Потребителят разглежда списък с продукти или резултати от търсене.
`select_item`	Потребителят кликва върху продукт в списък.
`view_item`	Потребителят разглежда страница с детайли за продукт.
`add_to_cart`	Потребителят добавя продукт в количката.
`remove_from_cart`	Потребителят премахва продукт от количката.
`view_cart`	Потребителят разглежда количката.
`add_to_wishlist`	Потребителят добавя продукт в списъка с желания.
`begin_checkout`	Потребителят започва процеса на плащане.
`add_shipping_info`	Потребителят изпраща информация за доставка.
`add_payment_info`	Потребителят изпраща информация за плащане.
`purchase`	Потребителят завършва покупка.
`refund`	Обработва се пълно или частично възстановяване.
`view_promotion`	Потребителят разглежда промоционален банер или оферта.
`select_promotion`	Потребителят кликва върху промоция.

view_item_list

Задействайте това събитие, когато потребителите видят списък с продукти, като страница на категория или резултати от търсене.

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

Задействайте това събитие, когато потребител кликне върху конкретен продукт от списък, за да го разгледа.

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

Задействайте това събитие, когато потребител попадне на страница с детайли за продукт.

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

Задействайте това събитие, когато потребител добави един или повече продукти в количката си.

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

Задействайте това събитие, когато потребител премахне продукт от количката си.

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

Задействайте това събитие, когато потребител разгледа страницата на количката си.

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

Задействайте това събитие, когато потребител запази продукт в списъка си с желания за по-късно.

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

Задействайте това събитие, когато потребител започне процеса на плащане.

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

Задействайте това събитие, когато потребител избере или изпрати данните си за доставка по време на плащане.

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

Задействайте това събитие, когато потребител избере или изпрати метода си на плащане по време на плащане.

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

Задействайте това събитие, когато покупката е потвърдена. Включете transaction_id, value, currency, tax, shipping и пълния 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

Задействайте това събитие, когато се обработи възстановяване. За пълно възстановяване е необходим само transaction_id. За частични възстановявания включете конкретните артикули.

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

Задействайте това събитие, когато промоционален банер, карусел или оферта станат видими за потребителя.

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

Задействайте това събитие, когато потребител кликне върху промоция, за да научи повече или да се възползва от офертата.

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

Миграция от Google Analytics

ClearAnalytics е проектиран да работи заедно с или като заместител на Google Analytics. Можете да стартирате и двата инструмента паралелно по време на миграцията без конфликти.

Стартиране на двата скрипта паралелно

Добавете скрипта на ClearAnalytics заедно с вашия съществуващ Google Analytics таг. И двата скрипта ще проследяват независимо, без да си пречат.

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

Съвместимост на функциите

Ето как функциите на ClearAnalytics съответстват на еквивалентите в Google Analytics:

Функция	Google Analytics	ClearAnalytics
Прегледи на страници	`gtag('event', 'page_view')`	Автоматично
Персонализирани събития	`gtag('event', ...)`	`window.ca('event')`
Електронна търговия	`dataLayer.push()`	dataLayer съвместим
UTM кампании	Автоматично	Автоматично
Сесии	Базиран на бисквитки	Без бисквитки

Стъпки за миграция

Добавете скрипта на ClearAnalytics към вашия сайт заедно с Google Analytics.
Активирайте прихващането на dataLayer с data-ca-datalayer, за да улавяте съществуващи събития на електронната търговия.
Сравнявайте данните в двете табла за 2-4 седмици, за да проверите точността.
Когато сте удовлетворени, премахнете скрипта на Google Analytics и се насладете на по-бърза настройка, зачитаща поверителността.

Поддръжка на SPA

ClearAnalytics автоматично открива навигация от страна на клиента в едностранични приложения. Не е необходима допълнителна конфигурация или интеграция с маршрутизатор.

Как работи

Скриптът прихваща извиквания на History API на браузъра за откриване на навигация по страници:

history.pushState() извикванията се прихващат и задействат нов преглед на страница.
history.replaceState() извикванията се прихващат и задействат нов преглед на страница.
popstate събитията (напред/назад в браузъра) задействат нов преглед на страница.

Съвместими рамки

Работи веднага с всяка рамка, използваща History API за маршрутизация:

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

Не са необходими плъгини за маршрутизатор, куки за жизнен цикъл или ръчни извиквания за проследяване. Просто добавете script тага веднъж и всяка навигация по страници се проследява автоматично.

Поверителност и съответствие

ClearAnalytics е изграден с поверителността в основата си. Скриптът за проследяване събира само анонимни, агрегирани данни. Лична информация никога не се съхранява или предава.

Без бисквитки

Скриптът не задава, не чете и не зависи от никакви бисквитки на браузъра. Не е необходим банер за съгласие за бисквитки.

Без отпечатъци

Никога не създаваме отпечатъци на браузъра. Не се използват техники за отпечатъци чрез canvas, WebGL, шрифтове или аудио.

Без съхранение на IP адреси

IP адресите на посетителите се използват само за анонимизирано хеширане по време на заявката. Те никога не се съхраняват в базата данни.

Съответствие с GDPR

Тъй като не се събират лични данни, ClearAnalytics попада извън обхвата на изискванията за съгласие по GDPR. Всички данни остават в ЕС.

Как анонимизираме посетителите

За да броим уникални посетители без съхранение на лични данни, използваме ежедневно ротиращ се анонимен хеш:

IP адресът на посетителя и User-Agent се комбинират с ежедневно ротираща се сол.
Тази комбинация се хешира с еднопосочен SHA-256 алгоритъм.
Солта се ротира на всеки 24 часа, което прави невъзможно проследяването на посетители между дни.
Оригиналният IP адрес никога не се съхранява или записва.

Данни, събирани от скрипта

Следните неперсонални полета с данни се изпращат с всяко събитие за преглед на страница:

Поле	Предназначение
`pathname`	URL пътят на посещаваната страница.
`referrer`	URL на препращащата страница, ако има такъв.
`language`	Езиковата настройка на браузъра.
`screen_width / screen_height`	Размери на екрана за класификация на типа устройство.
`utm_*`	Параметри за проследяване на кампании от URL адреса.
`duration`	Време, прекарано на страницата в секунди.

Тъй като ClearAnalytics никога не събира лични данни, не се нуждаете от банер за съгласие за бисквитки, изскачащ прозорец за поверителност или механизъм за съгласие, за да използвате нашия скрипт за проследяване. Той е съвместим с GDPR, ePrivacy, PECR и CCPA от кутията.