MyClub/DOCS/UMAMI_INTEGRATION.md

Umami Analytics Integration

This document describes the Umami analytics integration for the Fotbal Club application.

Overview

Umami is an open-source, privacy-focused web analytics platform integrated into both the backend (Go) and frontend (React/TypeScript). The integration automatically tracks page views and allows custom event tracking throughout the application.

Features

• ✅ Automatic page view tracking - Tracks all page visits automatically
• ✅ Custom event tracking - Track button clicks, form submissions, downloads, etc.
• ✅ Privacy-first - No cookies, GDPR compliant
• ✅ Admin analytics dashboard - View comprehensive statistics in the admin panel
• ✅ Auto-initialization - Automatically creates website tracking in Umami on production deployment
• ✅ Real-time data - Pull live data from Umami API

Configuration

Environment Variables

Add the following to your .env file:

# Umami Analytics
UMAMI_URL=https://umami.tdvorak.dev
UMAMI_USERNAME=admin
UMAMI_PASSWORD=eevRQ6h3G@!c#y4A1T
UMAMI_WEBSITE_ID=  # Leave empty for auto-create, or set manually after creation

Initial Setup

There are two ways to set up Umami tracking:

Option 1: Manual Setup

1. Log in to your Umami instance
2. Create a new website manually via the Umami UI
3. Copy the website ID
4. Set UMAMI_WEBSITE_ID in your .env file

Option 2: Automatic Setup (Recommended for Production)

The system can automatically create a website in Umami when deployed to a real domain:

1. Deploy your application to production
2. Log in to the admin panel
3. The system detects if running on a non-localhost domain
4. Call the initialization endpoint or use the settings page to trigger auto-setup
5. The website is created in Umami and the ID is stored

API Endpoint for Auto-Initialization:

POST /api/v1/admin/umami/initialize
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Fotbal Club",
  "domain": "fotbalclub.cz"
}

Response:

{
  "message": "Umami initialized successfully",
  "website_id": "7f23c6b1-9b9d-45e3-8a2d-99cabc21e7c0",
  "script_url": "https://umami.tdvorak.dev/script.js"
}

Architecture

Backend (Go)

Files:

• internal/config/config.go - Umami configuration
• internal/services/umami_service.go - Umami API client
• internal/controllers/umami_controller.go - HTTP endpoints
• internal/routes/routes.go - Route registration

API Endpoints:

Public:

• GET /api/v1/umami/config - Get Umami configuration for frontend

Admin:

• POST /api/v1/admin/umami/initialize - Initialize Umami tracking
• GET /api/v1/admin/umami/stats?days=30 - Get overview statistics
• GET /api/v1/admin/umami/metrics/:type?days=30 - Get specific metrics

Metric Types:

• url - Page views by URL
• referrer - Traffic sources
• browser - Browser usage
• os - Operating system usage
• device - Device types (desktop/mobile/tablet)
• country - Visitor countries
• event - Custom events

Frontend (React/TypeScript)

Files:

• frontend/src/hooks/useUmami.ts - React hook for Umami initialization
• frontend/src/utils/umami.ts - Event tracking utilities
• frontend/src/pages/admin/AnalyticsAdminPage.tsx - Analytics dashboard
• frontend/src/App.tsx - Umami hook integration

Hook Usage:

The Umami script is automatically loaded in App.tsx:

import { useUmami } from './hooks/useUmami';

const App: React.FC = () => {
  useUmami(); // Initializes Umami tracking
  // ... rest of app
};

Event Tracking

Using Data Attributes (HTML)

Add data-umami-event attributes to any element:

<button data-umami-event="Signup button">
  Sign up
</button>

// With additional data
<button 
  data-umami-event="Purchase"
  data-umami-event-product="Jersey"
  data-umami-event-price="500"
>
  Buy Jersey
</button>

Using JavaScript/TypeScript

Import tracking utilities and call them:

import { trackEvent, trackButtonClick, trackArticleView } from '../utils/umami';

// Generic event
trackEvent('Newsletter Subscribe', { source: 'footer' });

// Specific helpers
trackButtonClick('Download PDF', '/documents');
trackArticleView(article.id, article.title);
trackFormSubmit('Contact Form', true);
trackSocialShare('Facebook', url);
trackVideoPlay(video.id, video.title);
trackSearch(query, resultsCount);
trackDownload('brochure.pdf', 'pdf');
trackNewsletterSubscribe('homepage');
trackContactSubmit(true);

Available Helper Functions

All functions are in frontend/src/utils/umami.ts:

• trackEvent(name, data?) - Generic event tracking
• trackButtonClick(button, location?) - Track button clicks
• trackFormSubmit(form, success?) - Track form submissions
• trackNavigation(destination, source?) - Track page navigation
• trackArticleView(id, title) - Track article views
• trackMatchView(id) - Track match views
• trackSearch(query, resultsCount?) - Track search queries
• trackVideoPlay(id, title?) - Track video plays
• trackNewsletterSubscribe(source?) - Track newsletter signups
• trackDownload(file, type?) - Track file downloads
• trackSocialShare(platform, url?) - Track social shares
• trackContactSubmit(success?) - Track contact form submissions

Admin Dashboard

Access the analytics dashboard at /admin/analytika (admin login required).

Features:

• Overview statistics (pageviews, visitors, visits, bounce rate, average time)
• Time range selection (today, 7 days, 30 days, 90 days, 1 year)
• Detailed metrics tabs:
  • Most visited pages
  • Traffic sources (referrers)
  • Browser usage
  • Operating systems
  • Visitor countries
  • Device types
  • Custom events

Example Integration

Footer Social Links (Already Integrated)

// frontend/src/components/layout/Footer.tsx
import { trackSocialShare } from '../../utils/umami';

<IconButton
  href={facebookUrl}
  onClick={() => trackSocialShare('Facebook', facebookUrl)}
  // ... props
/>

Newsletter Subscription

import { trackNewsletterSubscribe } from '../utils/umami';

const handleSubscribe = async (email: string) => {
  try {
    await api.post('/newsletter/subscribe', { email });
    trackNewsletterSubscribe('footer-form');
    showSuccessToast();
  } catch (error) {
    // handle error
  }
};

Article View Tracking

import { trackArticleView } from '../utils/umami';

useEffect(() => {
  if (article) {
    trackArticleView(article.id, article.title);
  }
}, [article]);

Privacy & GDPR Compliance

Umami is privacy-focused by default:

• ✅ No cookies used
• ✅ No personal data collected
• ✅ Anonymized IP addresses
• ✅ GDPR compliant out of the box
• ✅ Data stored on your own infrastructure

Testing

Local Development

On localhost, Umami tracking is loaded but may not send data depending on configuration. Use the browser console to verify:

// Check if Umami is loaded
console.log(window.umami);

// Manually track an event
window.umami?.track('Test Event', { test: true });

Production Verification

1. Deploy to production
2. Open browser DevTools > Network tab
3. Filter by "umami" or your Umami domain
4. Navigate the site and trigger events
5. Verify requests are being sent
6. Check the admin dashboard for data

Troubleshooting

Script Not Loading

• Verify UMAMI_URL is correct
• Check UMAMI_WEBSITE_ID is set
• Ensure Umami server is accessible from client browsers
• Check browser console for errors

No Data in Dashboard

• Verify tracking script is loaded (check Network tab)
• Ensure events are being sent (check Network tab)
• Check Umami server logs
• Verify correct website ID is being used
• Allow a few minutes for data processing

API Authentication Fails

• Verify UMAMI_USERNAME and UMAMI_PASSWORD are correct
• Check Umami server is accessible from backend
• Verify API endpoints are correct (may differ by Umami version)

Security Notes

• Never commit real Umami credentials to version control
• Use environment variables for all sensitive data
• Restrict admin API access to authenticated users only
• Consider rate limiting on public tracking endpoints

Future Enhancements

Potential improvements:

• Real-time dashboard updates - WebSocket/SSE for live stats
• Custom dashboards - Create custom views for specific metrics
• Goal tracking - Define and track conversion goals
• A/B testing integration - Compare variants
• Alerting - Notifications for traffic spikes or anomalies
• Data export - Export analytics data for external analysis
• Heatmaps - Visual representation of user interactions (requires additional tooling)

Resources

• Umami Official Docs
• Umami API Reference
• Umami GitHub