1# Web Analytics Gotchas
2 
3## Critical Issues
4 
5### SPA Navigation Not Tracked
6 
7**Symptom:** Only initial pageload counted  
8**Fix:** Add `spa: true`:
9```html
10<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
11```
12 
13### CSP Blocking Beacon
14 
15**Symptom:** Console error "Refused to load script"  
16**Fix:** Allow both domains:
17```
18script-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com;
19```
20 
21### Hash-Based Routing Unsupported
22 
23**Symptom:** `#/path` URLs not tracked  
24**Fix:** Migrate to History API (`BrowserRouter`, not `HashRouter`). No workaround for hash routing.
25 
26### No Data Appearing
27 
28**Causes & Fixes:**
291. **Delay** - Wait 5-15 minutes
302. **Wrong token** - Verify matches dashboard exactly
313. **Script blocked** - Check DevTools Network tab for beacon.min.js
324. **Domain mismatch** - Dashboard site must match actual URL
33 
34### Auto-Injection Fails
35 
36**Cause:** `Cache-Control: no-transform` header  
37**Fix:** Remove `no-transform` or install beacon manually
38 
39### Duplicate Pageviews
40 
41**Cause:** Multiple beacon scripts  
42**Fix:** Keep only one beacon per page
43 
44## Configuration Issues
45 
46| Issue | Fix |
47|-------|-----|
48| 10-site limit reached | Delete old sites or proxy through CF (unlimited) |
49| Token not recognized | Use exact alphanumeric token from dashboard |
50 
51## Framework-Specific
52 
53### Next.js Hydration Warning
54 
55```tsx
56<script suppressHydrationWarning ... />
57```
58 
59### Gatsby Window Undefined
60 
61Use `gatsby-browser.js` to load client-side only.
62 
63## Limits
64 
65| Resource | Limit |
66|----------|-------|
67| Non-proxied sites | 10 |
68| Proxied sites | Unlimited |
69| Data retention | 6 months |
70| Ingestion delay | 5-10 min |
71| API access | None (dashboard only) |
72 
73## When NOT to Use Web Analytics
74 
75Use alternatives if you need:
76- Custom event tracking
77- Real-time data
78- User-level tracking
79- Conversion funnels
80- Data export/API access
81 
82**Web Analytics excels at:** Core Web Vitals, basic traffic, privacy compliance, free unlimited pageviews.
83