MyClub/DOCS/ANALYTICS_INTEGRATION.md

Integrace analytiky do dashboardu

Co bylo provedeno

1. Frontend změny

Analytické služby (frontend/src/services/analyticsService.ts)

• Přidány nové funkce pro práci s analytikou:
  • getAnalyticsOverview() - získání celkového přehledu (page views, visitors)
  • getTopPages() - nejnavštěvovanější stránky
  • getTopArticles() - nejčtenější články
  • getTopInteractions() - nejčastější interakce uživatelů
  • trackEvent() - odeslání tracking eventu na backend

Oprava trackingu (frontend/src/hooks/useUmami.ts)

• Hook nyní automaticky trackuje změny stránek (page views)
• Tracking probíhá současně do Umami i backend analytiky
• Využívá useLocation z React Router pro automatické sledování navigace

Utility funkce (frontend/src/utils/umami.ts)

• Všechny tracking funkce (trackButtonClick, trackFormSubmit, atd.) nyní posílají data:
  1. Do Umami (pokud je nakonfigurováno)
  2. Do backend analytiky
• trackButtonClick nyní trackuje i jako "interakci" pro backend analytics

Admin Dashboard (frontend/src/pages/admin/AdminDashboardPage.tsx)

• Nové statistiky v horní části:
  • Zobrazení stránek (celkem)
  • Unikátní návštěvníci
  • Zobrazení za týden
  • Zobrazení dnes
• Dvě nové analytické tabulky:
  • Nejnavštěvovanější stránky (top 5)
  • Nejčastější interakce za 7 dní (top 5)
• Odkazy na detailní stránku analytiky (/admin/analytika)

2. Backend změny

Model (internal/models/visitor_event.go)

Přidána nová pole do VisitorEvent:

• PagePath - úplná cesta stránky
• PageName - lidsky čitelný název stránky
• Data - generické JSONB pole pro libovolná event data

Controller (internal/controllers/analytics_controller.go)

• Automatická synchronizace Page a PagePath polí
• Přidán tracking Referrer hlavičky
• Zachování IP adresy v hashované podobě pro ochranu soukromí

Migrace (database/migrations/000009_*.sql)

• Přidání nových sloupců do tabulky visitor_events
• Vytvoření indexů pro rychlejší queries:
  • idx_visitor_events_page_path
  • idx_visitor_events_created_at
  • idx_visitor_events_event_type_created_at

Jak spustit

1. Spuštění migrací

# Nastavte RUN_MIGRATIONS=true v .env nebo spusťte:
go run main.go

Nebo manuálně:

cd database
migrate -path migrations -database "postgresql://user:pass@localhost:5432/fotbal_club?sslmode=disable" up

2. Restart backendu

go run main.go

3. Frontend

Frontend se automaticky připojí k novým endpointům. Pokud je frontend spuštěný, stačí obnovit stránku.

cd frontend
npm start

Testování

Test page view tracking

1. Otevřete aplikaci v prohlížeči
2. Navigujte mezi různými stránkami
3. V admin dashboardu (/admin) zkontrolujte:
   • Počet zobrazení stránek
   • Seznam nejnavštěvovanějších stránek

Test interaction tracking

1. Klikněte na různé tlačítka v aplikaci
2. V dashboardu zkontrolujte sekci "Nejčastější interakce"
3. Měly by se tam zobrazit elementy, na které jste klikali

Kontrola dat v databázi

-- Zobrazit poslední tracked eventy
SELECT event_type, page_path, page_name, created_at 
FROM visitor_events 
ORDER BY created_at DESC 
LIMIT 10;

-- Počet page views
SELECT COUNT(*) FROM visitor_events WHERE event_type = 'page_view';

-- Nejnavštěvovanější stránky
SELECT page_path, COUNT(*) as views 
FROM visitor_events 
WHERE event_type = 'page_view' 
GROUP BY page_path 
ORDER BY views DESC 
LIMIT 10;

API Endpointy

Veřejné

• POST /api/v1/analytics/track - tracking eventů (rate-limited)

Admin (vyžaduje autentizaci)

• GET /api/v1/admin/analytics/overview - celkový přehled
• GET /api/v1/admin/analytics/top-pages?limit=10 - top stránky
• GET /api/v1/admin/analytics/top-articles?limit=10 - top články
• GET /api/v1/admin/analytics/top-interactions?days=7&limit=10 - top interakce

Použití v kódu

Tracking page view (automaticky)

Page views se trackují automaticky při změně URL pomocí useUmami hooku v App.tsx.

Tracking tlačítka

import { trackButtonClick } from '@/utils/umami';

const handleClick = () => {
  trackButtonClick('Název tlačítka', '/aktualni/cesta');
  // ... zbytek logiky
};

Tracking formuláře

import { trackFormSubmit } from '@/utils/umami';

const handleSubmit = async (data) => {
  try {
    await submitForm(data);
    trackFormSubmit('Kontaktní formulář', true);
  } catch (error) {
    trackFormSubmit('Kontaktní formulář', false);
  }
};

Custom event

import { trackEvent } from '@/utils/umami';

trackEvent('Video Play', {
  video_id: '123',
  video_title: 'Góly týdne'
});

Poznámky

• Privacy-first: IP adresy jsou hashovány pomocí SHA-256 před uložením
• Dual tracking: Data se ukládají do vlastní DB i posílají do Umami (pokud je nakonfigurováno)
• Rate limiting: Public tracking endpoint je limitován na 120 requestů za minutu
• Performance: Tracking requesty neblokují UI, používají catch pro tichý fail
• GDPR: Sledování je anonymní, žádné cookies, žádné PII (personally identifiable information)

Troubleshooting

Tracking nefunguje

1. Zkontrolujte browser console - měly by být pouze console.debug zprávy
2. Zkontrolujte Network tab - měl by být POST request na /api/v1/analytics/track
3. Ověřte, že backend běží a je dostupný

Data se nezobrazují v dashboardu

1. Zkontrolujte, že migrace proběhla úspěšně
2. Ověřte data v databázi (viz SQL queries výše)
3. Zkontrolujte browser console pro chyby při načítání dat

Duplicitní tracking

• To je očekávané chování - data jdou současně do Umami i backend DB
• Pokud chcete vypnout jedno z nich, upravte kód v useUmami.ts nebo umami.ts