Wiki

Tracking.md

@@ -0,0 +1,67 @@
+# Tracking systém
+
+## Jak to funguje
+
+Tracking probíhá přes JavaScript soubor `public/collect.js`, který se vloží na sledovaný web. Každý web/eshop má přiřazený **Site Key** (`TrackingSite.public_key`), který se předává jako `data-site-key` atribut scriptu.
+
+```html
+<script src="https://app.domena.cz/collect.js"
+        data-site-key="abc123"
+        data-api-base="https://app.domena.cz">
+</script>
+```
+
+## Visitor ID
+
+- Každý anonymní návštěvník dostane náhodné `visitor_id` (UUID), které se ukládá do cookie `ft_vid` a localStorage.
+- Po identifikaci (přihlášení, vyplnění emailu) se `visitor_id` propojí s `Contact` přes tabulku `visitor_identities` – viz `IdentityLinker`.
+
+## IngestEvent pipeline
+
+Všechny eventy (browser i server-side) prochází přes `App\Services\Ingest\IngestEvent::ingest()`:
+
+1. Parsuje a normalizuje data (visitor_id, contact_id, occurred_at...)
+2. Volitelně provede identify (pokud přišel `identity.email`)
+3. Pokud chybí `visitor_id`, generuje náhradní (`contact:{id}` nebo `integration:{source}`)
+4. Uloží `FunnelEvent` do databáze (idempotentně přes `external_event_id`)
+5. Vrátí uložený `FunnelEvent`
+
+Po ingestion volají controllery `RulesEngine::evaluate()` – viz [Automations](Automations).
+
+## Události (event typy)
+
+| Event | Kdy se posílá |
+|-------|--------------|
+| `page_view` | Každé zobrazení stránky |
+| `cart_upsert` | Změna obsahu košíku |
+| `cart_completed` | Dokončení objednávky |
+| `newsletter_subscribe` | Přihlášení k newsletteru |
+| `gallery_config_submit` | Odeslání konfigurátoru |
+| `identify` | Identifikace návštěvníka |
+
+## Identifikace návštěvníka
+
+Třída `IdentityLinker` zajišťuje propojení `visitor_id → Contact`:
+
+- **`identify()`** – podle emailu (přihlášení, formulář)
+- **`identifyByToken()`** – podle `ftclid` (klik z emailové kampaně)
+- Mapping ukládá do `visitor_identities`
+- Backfilluje `contact_id` ke starším eventům pro stejné `visitor_id`
+
+## Automatická identifikace v collect.js
+
+1. Přes `ftclid` v URL (z emailového odkazu)
+2. Přes `gident` / `tag` UTM parametr
+3. Přes email v payloadu (při odeslání formuláře)
+
+## Bot detekce
+
+`BotDetector` flaguje requesty od crawlerů a botů. `FunnelEvent.bot = 1` pro botí eventy – tyto se do statistik nezapočítávají.
+
+## GTM / dataLayer integrace
+
+`collect.js` naslouchá na `window.dataLayer.push()` a zachytává standardní ecommerce eventy (`purchase`, `order_completed`, `transaction`, `ecommerce_purchase`) – automaticky je převede na `cart_completed`.
+
+## Cross-domain tracking
+
+Pokud zákazník přechází mezi doménami, `collect.js` automaticky doplňuje `visitor_id` jako URL parametr do odkazů podle konfigurace `data-propagate-link-domains`.