MyClub/DOCS/QUICK_START_ANALYTICS.md

Rychlý start - Analytika v dashboardu

✅ Co je hotovo

Backend

• ✅ Analytické endpointy (/admin/analytics/*)
• ✅ Model VisitorEvent s novými poli
• ✅ Migrace databáze (000009)
• ✅ Privacy-first tracking (hashované IP adresy)
• ✅ Rate limiting pro public endpoint

Frontend

• ✅ Admin dashboard zobrazuje analytiku
• ✅ Automatický tracking page views
• ✅ Tracking interakcí (clicks, formuláře)
• ✅ Dual tracking (Umami + vlastní backend)
• ✅ Tabulky top stránek a interakcí

🚀 Jak spustit

1. Migrace databáze

# V hlavní složce projektu
# Buď nastavit v .env:
RUN_MIGRATIONS=true

# Nebo spustit přímo
go run main.go

Migrace automaticky:

• Přidá sloupce page_path, page_name, data do tabulky visitor_events
• Vytvoří indexy pro rychlejší queries
• Zkopíruje existující data z page do page_path

2. Spuštění backendu

go run main.go

Server běží na http://localhost:8080 (nebo váš konfigurovaný port).

3. Spuštění frontendu

cd frontend
npm start

Frontend běží na http://localhost:3000.

📊 Co uvidíte v dashboardu

Horní statistiky (6 karet)

1. Uživatelé (admin) - celkový počet admin uživatelů
2. Události - nadcházející události
3. Články - celkem a publikované
4. Zobrazení stránek - celkový počet page views + dnes
5. Unikátní návštěvníci - celkem + tento týden
6. Zobrazení (týden) - za posledních 7 dní

Analytické tabulky (2 karty)

Nejnavštěvovanější stránky

Stránka	Zobrazení	Návštěvníci
/	145	89
/blog	87	56
/kontakt	34	28

Nejčastější interakce (7 dní)

Element	Stránka	Počet
Newsletter button	/	45
Contact form	/kontakt	23

Widgety

• Návštěvnost (graf za 30 dní)
• Nadcházející zápasy
• Poslední články
• Aktuální scoreboard

🧪 Testování

Otevřete aplikaci

http://localhost:3000

Navigujte mezi stránkami

1. Úvodní stránka /
2. Blog /blog
3. Kontakt /kontakt
4. O klubu /o-klubu

Klikejte na tlačítka

• Newsletter subscribe
• Odkazy v menu
• Tlačítka v článcích

Zkontrolujte admin dashboard

http://localhost:3000/admin

Po přihlášení byste měli vidět:

• Počet zobrazení stránek se zvyšuje
• V tabulce "Nejnavštěvovanější stránky" se objevují stránky, které jste navštívili
• V tabulce "Nejčastější interakce" se objevují elementy, na které jste klikli

🔍 Kontrola databáze

-- Počet tracked eventů
SELECT event_type, COUNT(*) as count 
FROM visitor_events 
GROUP BY event_type;

-- Poslední page views
SELECT page_path, page_name, created_at 
FROM visitor_events 
WHERE event_type = 'page_view' 
ORDER BY created_at DESC 
LIMIT 10;

-- Top stránky
SELECT page_path, COUNT(*) as views, COUNT(DISTINCT ip_address) as visitors
FROM visitor_events 
WHERE event_type = 'page_view'
GROUP BY page_path 
ORDER BY views DESC 
LIMIT 10;

-- Top interakce za posledních 7 dní
SELECT page, element, COUNT(*) as count
FROM visitor_events 
WHERE event_type IN ('click', 'interaction') 
  AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY page, element 
ORDER BY count DESC 
LIMIT 10;

📝 Příklady použití v kódu

Automatický tracking (už funguje)

Page views se trackují automaticky v App.tsx pomocí useUmami hooku.

Manuální tracking tlačítka

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

function MyComponent() {
  const handleNewsletterClick = () => {
    trackButtonClick('Newsletter Subscribe Button');
    // ... zbytek logiky
  };

  return (
    <button onClick={handleNewsletterClick}>
      Přihlásit se k odběru
    </button>
  );
}

Tracking formuláře

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

const handleSubmit = async (values) => {
  try {
    await api.post('/contact', values);
    trackFormSubmit('Contact Form', true);
    toast.success('Odesláno!');
  } catch (error) {
    trackFormSubmit('Contact Form', false);
    toast.error('Chyba při odesílání');
  }
};

Custom tracking

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

// Track článku
trackEvent('Article View', {
  article_id: article.id,
  article_title: article.title,
  category: article.category
});

// Track video play
trackEvent('Video Play', {
  video_id: video.id,
  video_title: video.title
});

// Track download
trackEvent('Download', {
  file_name: 'rozpis-zapasu.pdf',
  file_type: 'pdf'
});

🎯 Co dál?

Doporučené další kroky:

1. Spusťte aplikaci a nechte ji běžet pár dní pro sběr dat
2. Sledujte dashboard - všimněte si, které stránky jsou nejpopulárnější
3. Přidejte tracking na důležitá tlačítka ve vaší aplikaci
4. Analyzujte data - použijte insights k vylepšení UX

Volitelné rozšíření:

1. Grafy v detailní analytice (/admin/analytika)

   • Časové grafy návštěvnosti
   • Rozložení podle dne v týdnu
   • Top articles s trendy

2. Export dat - přidat možnost exportu do CSV/Excel

3. Real-time dashboard - WebSocket pro live tracking

4. Heatmapy - vizuální zobrazení, kam uživatelé klikají

5. Conversion tracking - sledování konkrétních cílů (registrace, newsletter, atd.)

⚠️ Poznámky

• Tracking je neblokující - pokud selže, neovlivní to UX
• Privacy-first - IP adresy jsou hashovány, žádné cookies
• Rate limit - 120 requestů/minutu na tracking endpoint
• Performance - indexy zajišťují rychlé queries i s velkým objemem dat
• Dual tracking - data jdou do Umami i vlastní DB současně

🐛 Troubleshooting

Server se nespouští

# Zkontrolujte porty
netstat -ano | findstr :8080

# Zkontrolujte DB connection
psql -U postgres -d fotbal_club -c "SELECT version();"

Migrace selhaly

# Zkontrolujte DB připojení v .env
cat .env | grep DB_

# Spusťte migrace manuálně
cd database
migrate -path migrations -database "your_connection_string" up

Tracking nefunguje

1. Otevřete Developer Tools (F12)
2. Zkontrolujte Network tab - měl by být POST na /api/v1/analytics/track
3. Zkontrolujte Console - měly by být debug zprávy
4. Ověřte, že backend běží a odpovídá

Data se nezobrazují

1. Zkontrolujte, že máte data v DB (SQL queries výše)
2. Obnovte stránku dashboardu (F5)
3. Zkontrolujte browser console pro chyby
4. Ověřte, že jste přihlášení jako admin

📞 Podpora

Pokud narazíte na problémy:

1. Zkontrolujte tento dokument
2. Přečtěte si ANALYTICS_INTEGRATION.md pro detaily
3. Zkontrolujte DB logs a browser console
4. Otevřete issue na GitHubu (pokud používáte)

---

Vše hotovo! 🎉 Analytika je připravena k použití.