TDvorak/MyClub
1
0
Fork 0
mirror of https://github.com/Dvorinka/MyClubServer.git synced 2026-06-04 02:32:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

upload

Browse Source
This commit is contained in:
Tomáš Dvořák
2025-10-16 13:32:05 +02:00
commit 12cba639b9
663 changed files with 168914 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS/UMAMI_INTEGRATION.md
+323
View File
@@ -0,0 +1,323 @@
# 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:
```env
# 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:**
```bash
POST /api/v1/admin/umami/initialize
Authorization: Bearer <admin-token>
Content-Type: application/json
{
"name": "Fotbal Club",
"domain": "fotbalclub.cz"
}
```
Response:
```json
{
"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`:
```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:
```tsx
<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:
```tsx
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)
```tsx
// frontend/src/components/layout/Footer.tsx
import { trackSocialShare } from '../../utils/umami';
<IconButton
href={facebookUrl}
onClick={() => trackSocialShare('Facebook', facebookUrl)}
// ... props
/>
```
### Newsletter Subscription
```tsx
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
```tsx
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:
```javascript
// 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](https://umami.is/docs)
- [Umami API Reference](https://umami.is/docs/api)
- [Umami GitHub](https://github.com/umami-software/umami)