mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-21 18:11:27 -07:00
update skills
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
# Cloudflare Web Analytics
|
||||
|
||||
Privacy-first web analytics providing Core Web Vitals, traffic metrics, and user insights without compromising visitor privacy.
|
||||
|
||||
## Overview
|
||||
|
||||
Cloudflare Web Analytics provides:
|
||||
- **Core Web Vitals** - LCP, FID, CLS, INP, TTFB monitoring
|
||||
- **Page views & visits** - Traffic patterns without cookies
|
||||
- **Referrers & paths** - Traffic sources and popular pages
|
||||
- **Device & browser data** - User agent breakdown
|
||||
- **Geographic data** - Country-level visitor distribution
|
||||
- **Privacy-first** - No cookies, fingerprinting, or PII collection
|
||||
- **Free** - No cost, unlimited pageviews
|
||||
|
||||
**Important:** Web Analytics is **dashboard-only**. No API exists for programmatic data access.
|
||||
|
||||
## Quick Start Decision Tree
|
||||
|
||||
```
|
||||
Is your site proxied through Cloudflare?
|
||||
├─ YES → Use automatic injection (configuration.md)
|
||||
│ ├─ Enable auto-injection in dashboard
|
||||
│ └─ No code changes needed (unless Cache-Control: no-transform)
|
||||
│
|
||||
└─ NO → Use manual beacon integration (integration.md)
|
||||
├─ Add JS snippet to HTML
|
||||
├─ Use spa: true for React/Vue/Next.js
|
||||
└─ Configure CSP if needed
|
||||
```
|
||||
|
||||
## Reading Order
|
||||
|
||||
1. **[configuration.md](configuration.md)** - Setup for proxied vs non-proxied sites
|
||||
2. **[integration.md](integration.md)** - Framework-specific beacon integration (React, Next.js, Vue, Nuxt, etc.)
|
||||
3. **[patterns.md](patterns.md)** - Common use cases (performance monitoring, GDPR consent, multi-site tracking)
|
||||
4. **[gotchas.md](gotchas.md)** - Troubleshooting (SPA tracking, CSP issues, hash routing limitations)
|
||||
|
||||
## When to Use Each File
|
||||
|
||||
- **Setting up for first time?** → Start with configuration.md
|
||||
- **Using React/Next.js/Vue/Nuxt?** → Go to integration.md for framework code
|
||||
- **Need GDPR consent loading?** → See patterns.md
|
||||
- **Beacon not loading or no data?** → Check gotchas.md
|
||||
- **SPA not tracking navigation?** → See integration.md for `spa: true` config
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Proxied vs Non-Proxied Sites
|
||||
|
||||
| Type | Description | Beacon Injection | Limit |
|
||||
|------|-------------|------------------|-------|
|
||||
| **Proxied** | DNS through Cloudflare (orange cloud) | Automatic or manual | Unlimited |
|
||||
| **Non-proxied** | External hosting, manual beacon | Manual only | 10 sites max |
|
||||
|
||||
### SPA Mode
|
||||
|
||||
**Critical for modern frameworks:**
|
||||
```json
|
||||
{"token": "YOUR_TOKEN", "spa": true}
|
||||
```
|
||||
|
||||
Without `spa: true`, client-side navigation (React Router, Vue Router, Next.js routing) will NOT be tracked. Only initial page loads will register.
|
||||
|
||||
### CSP Requirements
|
||||
|
||||
If using Content Security Policy, allow both domains:
|
||||
```
|
||||
script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Core Web Vitals Debugging
|
||||
- **LCP (Largest Contentful Paint)** - Identifies slow-loading hero images/elements
|
||||
- **FID (First Input Delay)** - Interaction responsiveness (legacy metric)
|
||||
- **INP (Interaction to Next Paint)** - Modern interaction responsiveness metric
|
||||
- **CLS (Cumulative Layout Shift)** - Visual stability issues
|
||||
- **TTFB (Time to First Byte)** - Server response performance
|
||||
|
||||
Dashboard shows top 5 problematic elements with CSS selectors for debugging.
|
||||
|
||||
### Traffic Filters
|
||||
- **Bot filtering** - Exclude automated traffic from metrics
|
||||
- **Date ranges** - Custom time period analysis
|
||||
- **Geographic** - Country-level filtering
|
||||
- **Device type** - Desktop, mobile, tablet breakdown
|
||||
- **Browser/OS** - User agent filtering
|
||||
|
||||
### Rules (Advanced - Plan-dependent)
|
||||
|
||||
Create custom tracking rules for advanced configurations:
|
||||
|
||||
**Sample Rate Rules:**
|
||||
- Reduce data collection percentage for high-traffic sites
|
||||
- Example: Track only 50% of visitors to reduce volume
|
||||
|
||||
**Path-Based Rules:**
|
||||
- Different behavior per route
|
||||
- Example: Exclude `/admin/*` or `/internal/*` from tracking
|
||||
|
||||
**Host-Based Rules:**
|
||||
- Multi-domain configurations
|
||||
- Example: Separate tracking for staging vs production subdomains
|
||||
|
||||
**Availability:** Rules feature depends on your Cloudflare plan. Check dashboard under Web Analytics → Rules to see if available. Free plans may have limited or no access.
|
||||
|
||||
## Plan Limits
|
||||
|
||||
| Feature | Free | Notes |
|
||||
|---------|------|-------|
|
||||
| Proxied sites | Unlimited | DNS through Cloudflare |
|
||||
| Non-proxied sites | 10 | External hosting |
|
||||
| Pageviews | Unlimited | No volume limits |
|
||||
| Data retention | 6 months | Rolling window |
|
||||
| Rules | Plan-dependent | Check dashboard |
|
||||
|
||||
## Privacy & Compliance
|
||||
|
||||
- **No cookies** - Zero client-side storage
|
||||
- **No fingerprinting** - No tracking across sites
|
||||
- **No PII** - IP addresses not stored
|
||||
- **GDPR-friendly** - Minimal data collection
|
||||
- **CCPA-compliant** - No personal data sale
|
||||
|
||||
**EU opt-out:** Dashboard option to exclude EU visitor data entirely.
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Dashboard-only** - No API for programmatic access
|
||||
- **No real-time** - 5-10 minute data delay
|
||||
- **No custom events** - Automatic pageview/navigation tracking only
|
||||
- **History API only** - Hash-based routing (`#/path`) not supported
|
||||
- **No session replay** - Metrics only, no user recordings
|
||||
- **No form tracking** - Page navigation tracking only
|
||||
|
||||
## See Also
|
||||
|
||||
- [Cloudflare Web Analytics Docs](https://developers.cloudflare.com/analytics/web-analytics/)
|
||||
- [Core Web Vitals Guide](https://web.dev/vitals/)
|
||||
@@ -0,0 +1,76 @@
|
||||
# Configuration
|
||||
|
||||
## Setup Methods
|
||||
|
||||
### Proxied Sites (Automatic)
|
||||
|
||||
Dashboard → Web Analytics → Add site → Select hostname → Done
|
||||
|
||||
| Injection Option | Description |
|
||||
|------------------|-------------|
|
||||
| Enable | Auto-inject for all visitors (default) |
|
||||
| Enable, excluding EU | No injection for EU (GDPR) |
|
||||
| Enable with manual snippet | You add beacon manually |
|
||||
| Disable | Pause tracking |
|
||||
|
||||
**Fails if response has:** `Cache-Control: public, no-transform`
|
||||
|
||||
**CSP required:**
|
||||
```
|
||||
script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
|
||||
```
|
||||
|
||||
### Non-Proxied Sites (Manual)
|
||||
|
||||
Dashboard → Web Analytics → Add site → Enter hostname → Copy snippet
|
||||
|
||||
```html
|
||||
<script defer src='https://static.cloudflareinsights.com/beacon.min.js'
|
||||
data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'></script>
|
||||
```
|
||||
|
||||
**Limits:** 10 non-proxied sites per account
|
||||
|
||||
## SPA Mode
|
||||
|
||||
**Enable `spa: true` for:** React Router, Next.js, Vue Router, Nuxt, SvelteKit, Angular
|
||||
|
||||
**Keep `spa: false` for:** Traditional multi-page apps, static sites, WordPress
|
||||
|
||||
**Hash routing (`#/path`) NOT supported** - use History API routing.
|
||||
|
||||
## Token Management
|
||||
|
||||
- Found in: Dashboard → Web Analytics → Manage site
|
||||
- **Not secrets** - domain-locked, safe to expose in HTML
|
||||
- Each site gets unique token
|
||||
|
||||
## Environment Config
|
||||
|
||||
```typescript
|
||||
// Only load in production
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// Load beacon
|
||||
}
|
||||
```
|
||||
|
||||
Or use environment-specific tokens via env vars.
|
||||
|
||||
## Verify Installation
|
||||
|
||||
1. DevTools Network → filter `cloudflareinsights` → see `beacon.min.js` + data request
|
||||
2. No CSP/CORS errors in console
|
||||
3. Dashboard shows pageviews after 5-10 min delay
|
||||
|
||||
## Rules (Plan-dependent)
|
||||
|
||||
Configure in dashboard for:
|
||||
- **Sample rate** - reduce collection % for high-traffic
|
||||
- **Path-based** - different behavior per route
|
||||
- **Host-based** - separate tracking per domain
|
||||
|
||||
## Data Retention
|
||||
|
||||
- 6 months rolling window
|
||||
- 1-hour bucket granularity
|
||||
- No raw export, dashboard only
|
||||
@@ -0,0 +1,82 @@
|
||||
# Web Analytics Gotchas
|
||||
|
||||
## Critical Issues
|
||||
|
||||
### SPA Navigation Not Tracked
|
||||
|
||||
**Symptom:** Only initial pageload counted
|
||||
**Fix:** Add `spa: true`:
|
||||
```html
|
||||
<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
|
||||
|
||||
```tsx
|
||||
<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.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Framework Integration
|
||||
|
||||
**Web Analytics is dashboard-only** - no programmatic API. This covers beacon integration.
|
||||
|
||||
## Basic HTML
|
||||
|
||||
```html
|
||||
<script defer src='https://static.cloudflareinsights.com/beacon.min.js'
|
||||
data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'></script>
|
||||
```
|
||||
|
||||
Place before closing `</body>` tag.
|
||||
|
||||
## Framework Examples
|
||||
|
||||
| Framework | Location | Notes |
|
||||
|-----------|----------|-------|
|
||||
| React/Vite | `public/index.html` | Add `spa: true` |
|
||||
| Next.js App Router | `app/layout.tsx` | Use `<Script strategy="afterInteractive">` |
|
||||
| Next.js Pages | `pages/_document.tsx` | Use `<Script>` |
|
||||
| Nuxt 3 | `app.vue` with `useHead()` | Or use plugin |
|
||||
| Vue 3/Vite | `index.html` | Add `spa: true` |
|
||||
| Gatsby | `gatsby-browser.js` | `onClientEntry` hook |
|
||||
| SvelteKit | `src/app.html` | Before `</body>` |
|
||||
| Astro | Layout component | Before `</body>` |
|
||||
| Angular | `src/index.html` | Add `spa: true` |
|
||||
| Docusaurus | `docusaurus.config.js` | In `scripts` array |
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "YOUR_TOKEN",
|
||||
"spa": true
|
||||
}
|
||||
```
|
||||
|
||||
**Use `spa: true` for:** React Router, Vue Router, Next.js, Nuxt, Gatsby, SvelteKit, Angular
|
||||
|
||||
**Use `spa: false` for:** Traditional server-rendered (PHP, Django, Rails, WordPress)
|
||||
|
||||
## CSP Headers
|
||||
|
||||
```
|
||||
script-src 'self' https://static.cloudflareinsights.com;
|
||||
connect-src 'self' https://cloudflareinsights.com;
|
||||
```
|
||||
|
||||
## GDPR Consent
|
||||
|
||||
```typescript
|
||||
// Load conditionally based on consent
|
||||
if (localStorage.getItem('analytics-consent') === 'true') {
|
||||
const script = document.createElement('script');
|
||||
script.src = 'https://static.cloudflareinsights.com/beacon.min.js';
|
||||
script.defer = true;
|
||||
script.setAttribute('data-cf-beacon', '{"token": "YOUR_TOKEN", "spa": true}');
|
||||
document.body.appendChild(script);
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,91 @@
|
||||
# Web Analytics Patterns
|
||||
|
||||
## Core Web Vitals Debugging
|
||||
|
||||
Dashboard → Core Web Vitals → Click metric → Debug View shows top 5 problematic elements.
|
||||
|
||||
### LCP Fixes
|
||||
|
||||
```html
|
||||
<!-- Priority hints -->
|
||||
<img src="hero.jpg" loading="eager" fetchpriority="high" />
|
||||
<link rel="preload" as="image" href="/hero.jpg" fetchpriority="high" />
|
||||
```
|
||||
|
||||
### CLS Fixes
|
||||
|
||||
```css
|
||||
/* Reserve space */
|
||||
.ad-container { min-height: 250px; }
|
||||
img { width: 400px; height: 300px; } /* Explicit dimensions */
|
||||
```
|
||||
|
||||
### INP Fixes
|
||||
|
||||
```typescript
|
||||
// Debounce expensive operations
|
||||
const handleInput = debounce(search, 300);
|
||||
|
||||
// Yield to main thread
|
||||
await task(); await new Promise(r => setTimeout(r, 0)); await task2();
|
||||
|
||||
// Move to Web Worker for heavy computation
|
||||
```
|
||||
|
||||
| Metric | Good | Poor |
|
||||
|--------|------|------|
|
||||
| LCP | ≤2.5s | >4s |
|
||||
| INP | ≤200ms | >500ms |
|
||||
| CLS | ≤0.1 | >0.25 |
|
||||
|
||||
## GDPR Consent
|
||||
|
||||
```typescript
|
||||
// Load beacon only after consent
|
||||
const consent = localStorage.getItem('analytics-consent');
|
||||
if (consent === 'accepted') {
|
||||
const script = document.createElement('script');
|
||||
script.src = 'https://static.cloudflareinsights.com/beacon.min.js';
|
||||
script.setAttribute('data-cf-beacon', '{"token": "TOKEN", "spa": true}');
|
||||
document.body.appendChild(script);
|
||||
}
|
||||
```
|
||||
|
||||
Alternative: Dashboard → "Enable, excluding visitor data in the EU"
|
||||
|
||||
## SPA Navigation
|
||||
|
||||
```html
|
||||
<!-- REQUIRED for React/Vue/etc routing -->
|
||||
<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
|
||||
```
|
||||
|
||||
Without `spa: true`: only initial pageload tracked.
|
||||
|
||||
## Staging/Production Separation
|
||||
|
||||
```typescript
|
||||
// Use env-specific tokens
|
||||
const token = process.env.NEXT_PUBLIC_CF_ANALYTICS_TOKEN;
|
||||
// .env.production: production token
|
||||
// .env.staging: staging token (or empty to disable)
|
||||
```
|
||||
|
||||
## Bot Filtering
|
||||
|
||||
Dashboard → Filters → "Exclude Bot Traffic"
|
||||
|
||||
Filters: Search crawlers, monitoring services, known bots.
|
||||
Not filtered: Headless browsers (Playwright/Puppeteer).
|
||||
|
||||
## Ad-Blocker Impact
|
||||
|
||||
~25-40% of users may block `cloudflareinsights.com`. No official workaround.
|
||||
Dashboard shows minimum baseline; use server logs for complete picture.
|
||||
|
||||
## Limitations
|
||||
|
||||
- No UTM parameter tracking
|
||||
- No webhooks/alerts/API
|
||||
- No custom beacon domains
|
||||
- Max 10 non-proxied sites
|
||||
Reference in New Issue
Block a user