MyClub/DOCS/ANALYTICS_TEST_INSTRUCTIONS.md

Analytics Graph Fix - Testing Instructions

What Was Fixed

1. Frontend Improvements

• Added error detection: The page now detects when Umami returns no data
• Visual feedback: Orange warning banner appears when analytics are not configured
• Empty state display: Graph shows a clear message when no data is available
• Better error messages: Czech language messages explaining the issue

2. Backend Improvements

• Enhanced logging: Detailed logs at every step of Umami connection
• Auto-detection: System automatically finds the first Umami website if UMAMI_WEBSITE_ID is empty
• Better error handling: Graceful fallback when Umami is unreachable

How to Test

Step 1: Restart Backend

Restart your backend to apply the changes:

# If using Docker:
docker-compose restart backend

# Or rebuild if needed:
docker-compose up -d --build backend

# If running locally:
make run
# or
go run main.go

Step 2: Watch Backend Logs

Open a terminal and watch the logs:

# Docker:
docker-compose logs -f backend

# Local:
# Logs will appear in the terminal where you run the server

Step 3: Access Analytics Page

1. Open your browser
2. Go to: http://localhost:3000/admin/analytika (or your frontend URL)
3. Log in as admin if needed

Step 4: Observe the Behavior

Scenario A: Umami is Properly Connected

You should see:

• Backend logs:

  [INFO] UMAMI_WEBSITE_ID is empty, attempting to auto-detect...
  [INFO] Attempting to get default Umami website ID from https://umami.tdvorak.dev
  [INFO] Successfully authenticated with Umami at https://umami.tdvorak.dev
  [INFO] Found default Umami website: ID=xxxxx, Name=..., Domain=...
  [INFO] Auto-detected and cached Umami website ID: xxxxx
  [INFO] Using Umami website ID: xxxxx
  [INFO] Successfully fetched Umami stats for websiteID=xxxxx (days=0)
  

• Frontend display:

  • Statistics cards showing numbers (may be 0 if no traffic yet)
  • Graph displaying page views (or empty state if no data)
  • Country flags showing visitor locations

Scenario B: No Data Yet (Normal for New Sites)

You should see:

• Backend logs: Successful connection messages
• Frontend display:
  • Orange warning banner: "Analytika není k dispozici"
  • Message: "Umami není správně nakonfigurováno nebo ještě nebyly zaznamenány žádné návštěvy"
  • Empty graph with "Žádná data pro zobrazení"

Scenario C: Umami Connection Failed

You should see:

• Backend logs:

  [ERROR] Failed to resolve Umami website ID: ...
  [WARN] No Umami websites found in instance at https://umami.tdvorak.dev
  

• Frontend display:

  • Orange warning banner with error message
  • All statistics showing 0
  • Empty graph

Step 5: Generate Test Traffic (Optional)

To populate the analytics with data:

1. Open your website in multiple tabs/browsers
2. Navigate to different pages
3. Wait 2-5 minutes for Umami to process the data
4. Refresh the analytics page
5. You should now see data in the graphs

Expected Log Output (Success Case)

2025-01-14 13:45:23 [INFO] UMAMI_WEBSITE_ID is empty, attempting to auto-detect...
2025-01-14 13:45:23 [INFO] Attempting to find Umami website by domain: localhost
2025-01-14 13:45:23 [INFO] Attempting to get default Umami website ID from https://umami.tdvorak.dev
2025-01-14 13:45:23 [INFO] Successfully authenticated with Umami at https://umami.tdvorak.dev (new token issued, expires at 2025-01-15 12:45:23)
2025-01-14 13:45:24 [INFO] Found default Umami website: ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890, Name=My Fotbal Club, Domain=fotbalclub.example.com
2025-01-14 13:45:24 [INFO] Auto-detected and cached Umami website ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
2025-01-14 13:45:24 [INFO] Using Umami website ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
2025-01-14 13:45:25 [INFO] Successfully fetched Umami stats for websiteID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 (days=0)
2025-01-14 13:45:25 [INFO] Successfully fetched 0 Umami metrics (websiteID=a1b2c3d4-e5f6-7890-abcd-ef1234567890, type=url, days=0)

Troubleshooting

Issue: Backend logs show "No websites found"

Fix: Log into Umami (https://umami.tdvorak.dev) and create a website:

1. Click "Add Website"
2. Enter name: "Fotbal Club"
3. Enter domain: your website domain
4. Click "Save"
5. Restart backend

Issue: Backend logs show "Authentication failed"

Fix: Check credentials in .env:

UMAMI_URL=https://umami.tdvorak.dev
UMAMI_USERNAME=admin
UMAMI_PASSWORD=eevRQ6h3G@!c#y4A1T

Issue: Backend logs show connection timeout

Fix:

1. Check if Umami is running: curl https://umami.tdvorak.dev
2. Check firewall/network settings
3. Verify UMAMI_URL is correct

Issue: Graph shows but says "Žádná data"

Fix: This is normal! It means:

• Umami is connected ✓
• Website ID is detected ✓
• But no traffic has been recorded yet
• Solution: Visit your website and wait a few minutes

Files Modified

1. frontend/src/pages/admin/AnalyticsAdminPage.tsx

   • Added error detection and display
   • Added empty state for graphs
   • Better visual feedback

2. internal/controllers/umami_controller.go

   • Enhanced logging at each step
   • Better error messages
   • Improved website ID resolution

3. internal/services/umami_service.go

   • Added detailed logging for authentication
   • Better error messages for website detection

Next Steps After Successful Test

1. Optional: Set UMAMI_WEBSITE_ID in .env to avoid auto-detection on every restart
2. Monitor backend logs for any Umami-related errors
3. Check analytics page periodically to see real traffic data
4. Share the Umami dashboard URL with your team for detailed analytics

Support

If you continue to experience issues:

1. Check the full backend logs
2. Verify Umami is accessible
3. Review ANALYTICS_GRAPH_FIX.md for detailed solutions