Analytické trackování

UpSearch Plugin obsahuje vestavěný systém pro sledování uživatelských interakcí. Tato příručka popisuje architekturu trackingu, dostupné události a způsob integrace s vašimi analytickými nástroji.

Přehled

Plugin automaticky odesílá události o interakcích uživatelů s vyhledáváním. Tracking využívá multi-tracker architekturu, která umožňuje posílat data do více analytických služeb současně.

Podporované trackery

Tracker	Popis	Aktivace
PB Tracker	Posílá data přes window.analytics.track() (Segment)	Automaticky, pokud existuje window.analytics.track
GTM Tracker	Pushuje události do window.dataLayer	Manuální aktivace (viz níže)
Console Tracker	Loguje události do konzole prohlížeče	Vždy aktivní (pouze pro debugging)

Automatická aktivace

Tracking se aktivuje automaticky, pokud je na stránce dostupný Segment analytics:

// Tracking funguje automaticky, pokud existuje:
window.analytics.track(eventName, eventData, source);

Pokud window.analytics.track neexistuje, události se pouze logují do konzole (vhodné pro vývoj).

Sledované události

Základní události

Event	Název	Popis
show_results	Zobrazení výsledků	Spouští se při zobrazení výsledků v autocomplete nebo na SERP
select	Výběr položky	Kliknutí na produkt, kategorii, značku nebo článek
addtocart	Přidání do košíku	Přidání produktu do košíku z výsledků
hide	Zavření našeptávače	Zavření autocomplete boxu

Filtrační události

Event	Popis
upsearch_filter_search	Změna filtru na stránce výsledků
upsearch_filter_autocomplete	Změna filtru v autocomplete
upsearch_filterreset_search	Reset filtrů na stránce výsledků
upsearch_filterreset_autocomplete	Reset filtrů v autocomplete

Interní události (neposílají se)

Následující události jsou interně deaktivované a neposílají se do trackerů:

• focus - Fokus na vyhledávací input
• clear - Vymazání vyhledávacího inputu
• reset_results - Reset výsledků
• showcompleteresults - Klik na "Zobrazit všechny výsledky"

Struktura událostí

Společná data

Každá událost obsahuje společná data:

{
  event: string,           // Název události
  kind: 'autocomplete' | 'search' | 'tracker',  // Typ komponenty
  client_id: string,       // API token projektu
  browser_id: string,      // Unikátní ID prohlížeče (UUID v localStorage)
  path: string,            // Aktuální URL path
  title: string,           // Title stránky
}

Událost show_results

Odesílá se při zobrazení výsledků vyhledávání:

{
  event: 'show_results',
  kind: 'autocomplete',
  q: 'iPhone',                    // Původní dotaz
  q_transformed: 'iphone',        // Normalizovaný dotaz
  no_results: false,              // Zda jsou výsledky prázdné
  pagination: 1,                  // Číslo stránky (pouze SERP)
  products: [                     // Seznam produktů
    {
      id: '12345',
      code: 'PROD-001',
      name: 'iPhone 15 Pro',
      price: 29990,
      old_price: 32990,
      discount_in_percent: 9,
      list: 'upsearch_products',
      position: 1,
      breadcrumb: 'Elektronika > Mobily',
      badges: ['Novinka', 'Sleva']
    }
  ],
  categories: [                   // Seznam kategorií
    {
      name: 'Mobilní telefony',
      list: 'upsearch_categories',
      position: 1
    }
  ],
  brands: [                       // Seznam značek
    {
      name: 'Apple',
      list: 'upsearch_brands',
      position: 1
    }
  ],
  phrases: [                      // Návrhy frází
    {
      name: 'iphone 15',
      list: 'upsearch_phrases',
      position: 1
    }
  ]
}

Událost select

Odesílá se při kliknutí na položku ve výsledcích:

{
  event: 'select',
  kind: 'autocomplete',
  q: 'iPhone',
  q_transformed: 'iphone',
  no_results: false,
  products: [
    {
      id: '12345',
      name: 'iPhone 15 Pro',
      price: 29990,
      list: 'upsearch_products',
      position: 1
    }
  ]
}

Událost addtocart

Odesílá se při přidání produktu do košíku:

{
  event: 'addtocart',
  kind: 'search',
  products: [
    {
      id: '12345',
      code: 'PROD-001',
      name: 'iPhone 15 Pro',
      price: 29990,
      list: 'upsearch_products',
      position: 1,
      qty: 1
    }
  ]
}

Událost filtru

Odesílá se při změně filtru:

// Checkbox filtr
{
  event: 'upsearch_filter_search',
  upsearch_filter_search: {
    filter_name: 'Značka',
    filter_id: 'brand',
    filter_value: 'Apple'
  }
}

// Slider filtr (rozsah)
{
  event: 'upsearch_filter_search',
  upsearch_filter_search: {
    filter_name: 'Cena',
    filter_id: 'price',
    filter_value_from: '1000',
    filter_value_to: '5000'
  }
}

Identifikace prohlížeče

Plugin automaticky generuje a ukládá unikátní ID prohlížeče:

// Ukládá se do localStorage pod klíčem:
localStorage.getItem('upSearchBrowserId');  // UUID v4

Toto ID umožňuje sledovat uživatele napříč sessions bez potřeby cookies.

Integrace s Google Tag Manager

Pro aktivaci GTM trackeru je potřeba upravit inicializaci trackerů. GTM tracker pushuje události přímo do window.dataLayer:

// Událost se objeví v dataLayer jako:
window.dataLayer.push({
  event: 'show_results',
  kind: 'autocomplete',
  q: 'iPhone',
  // ... další data
});

Nastavení GTM triggerů

V Google Tag Manager vytvořte triggery pro jednotlivé události:

Trigger	Typ	Event name
UpSearch Results	Custom Event	show_results
UpSearch Select	Custom Event	select
UpSearch Add to Cart	Custom Event	addtocart
UpSearch Hide	Custom Event	hide

Příklad GTM tagu pro GA4

// Tag typu: Google Analytics: GA4 Event
// Trigger: UpSearch Results

Event Name: upsearch_show_results
Event Parameters:
  - search_term: {{DLV - q}}
  - results_count: {{DLV - products.length}}
  - no_results: {{DLV - no_results}}

Integrace se Segment

PB Tracker využívá Segment analytics. Události se odesílají ve formátu:

window.analytics.track(
  'show_results',           // Event name
  { /* event data */ },     // Event properties
  'upsearch'                // Source identifier
);

Debugging

Console logging

Všechny události se vždy logují do konzole prohlížeče (i v produkci):

// V DevTools uvidíte:
Event {event: 'show_results', kind: 'autocomplete', q: 'test', ...}

Kontrola aktivních trackerů

Zkontrolujte, zda je tracking aktivní:

// V konzoli prohlížeče:
typeof window.analytics?.track === 'function'  // true = PB Tracker aktivní
Array.isArray(window.dataLayer)                // true = GTM je připraven

Typy seznamů (lists)

Události používají následující identifikátory seznamů:

List	Popis
upsearch_products	Produktové výsledky
upsearch_categories	Kategorie
upsearch_brands	Značky/výrobci
upsearch_articles	Články
upsearch_pages	Stránky
upsearch_phrases	Návrhy frází

Typy vyhledávání (kind)

Kind	Komponenta	Popis
autocomplete	upSearchSuggest	Našeptávač v hlavičce
search	upSearchResults	Stránka s výsledky (SERP)
tracker	upSearchTracker	Samostatný tracker

Debouncing

Události v autocomplete jsou odesílány s debounce 750ms, aby se zabránilo přílišnému množství requestů během psaní.

Příklad kompletního flow

1. Uživatel začne psát do vyhledávání
2. Po 750ms se odešle show_results s autocomplete výsledky
3. Uživatel klikne na produkt → odešle se select
4. Uživatel přidá produkt do košíku → odešle se addtocart
5. Uživatel zavře našeptávač → odešle se hide

Řešení problémů

Události se neodesílají

1. Zkontrolujte, zda existuje window.analytics.track:

   console.log(typeof window.analytics?.track);

2. Ověřte, že Segment snippet je načten před UpSearch pluginem

3. Zkontrolujte konzoli pro chyby

Události jsou v konzoli, ale ne v analytics

• Segment/GTM snippet se načetl po UpSearch pluginu
• Zkontrolujte síťové requesty v DevTools → Network

Chybí některá data v událostech

• Některé vlastnosti (např. old_price, badges) se odesílají pouze pokud existují v datech produktu
• Prázdná pole se automaticky odstraňují z události