dotfiles/.agents/skills/cloudflare-deploy/references/web-analytics/gotchas.md

Web Analytics Gotchas

Critical Issues

SPA Navigation Not Tracked

Symptom: Only initial pageload counted
Fix: Add spa: true:

<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>

CSP Blocking Beacon

Symptom: Console error "Refused to load script"
Fix: Allow both domains:

script-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com;

Hash-Based Routing Unsupported

Symptom: #/path URLs not tracked
Fix: Migrate to History API (BrowserRouter, not HashRouter). No workaround for hash routing.

No Data Appearing

Causes & Fixes:

1. Delay - Wait 5-15 minutes
2. Wrong token - Verify matches dashboard exactly
3. Script blocked - Check DevTools Network tab for beacon.min.js
4. Domain mismatch - Dashboard site must match actual URL

Auto-Injection Fails

Cause: Cache-Control: no-transform header
Fix: Remove no-transform or install beacon manually

Duplicate Pageviews

Cause: Multiple beacon scripts
Fix: Keep only one beacon per page

Configuration Issues

Issue	Fix
10-site limit reached	Delete old sites or proxy through CF (unlimited)
Token not recognized	Use exact alphanumeric token from dashboard

Framework-Specific

Next.js Hydration Warning

<script suppressHydrationWarning ... />

Gatsby Window Undefined

Use gatsby-browser.js to load client-side only.

Limits

Resource	Limit
Non-proxied sites	10
Proxied sites	Unlimited
Data retention	6 months
Ingestion delay	5-10 min
API access	None (dashboard only)

When NOT to Use Web Analytics

Use alternatives if you need:

• Custom event tracking
• Real-time data
• User-level tracking
• Conversion funnels
• Data export/API access

Web Analytics excels at: Core Web Vitals, basic traffic, privacy compliance, free unlimited pageviews.