Cloudflare Web Analytics

Privacy-first, free web analytics with Core Web Vitals, real user monitoring, and automatic SPA support.

Quick Reference

Key Features

Feature	Description
Privacy-First	No cookies, no personal data, no fingerprinting
Free	Available on all Cloudflare plans including free
Core Web Vitals	LCP, CLS, INP, FCP metrics
SPA Support	Automatic single-page application tracking
No DNS Required	Works without Cloudflare proxy
6-Month Retention	Historical data access

Setup Methods

Method	When to Use
Automatic	Sites proxied through Cloudflare
Manual JS	Non-proxied sites, custom control
Pages	Cloudflare Pages projects (one-click)

Installation

Automatic Setup (Proxied Sites)

For sites already using Cloudflare's proxy:

1. Go to Analytics & Logs > Web Analytics in Cloudflare dashboard
2. Select your hostname from the dropdown
3. Web Analytics is enabled by default

Note: Sites with Cache-Control: public, no-transform headers require manual setup.

Manual JavaScript Snippet

Add before the closing </body> tag:

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js"
  data-cf-beacon='{"token": "YOUR_SITE_TOKEN"}'
></script>

Get your token:

1. Go to Web Analytics in Cloudflare dashboard
2. Click Add a site
3. Enter your hostname
4. Copy the generated snippet

Cloudflare Pages

1. Go to your Pages project
2. Navigate to Metrics section
3. Click Enable Web Analytics
4. Analytics automatically added on next deployment

Beacon Configuration

Basic Configuration

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js"
  data-cf-beacon='{"token": "YOUR_TOKEN"}'
></script>

Configuration Options

Option	Type	Default	Description
token	string	required	Your site token
spa	boolean	true	Enable SPA tracking

Disable SPA Tracking

Using data attribute:

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js"
  data-cf-beacon='{"token": "YOUR_TOKEN", "spa": false}'
></script>

Using query string (GTM):

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js?token=YOUR_TOKEN&spa=false"
></script>

Single Page Application (SPA) Support

How It Works

Cloudflare Web Analytics automatically tracks SPA navigation by:

1. Overriding the pushState method
2. Listening to onpopstate events
3. Sending measurements when routes change

Route changes send data for the previous route to the beacon endpoint. The last route measurement is sent when the user leaves the tab using Navigator.sendBeacon.

Supported Frameworks

Framework	Support
React	Full
Vue.js	Full
Angular	Full
Next.js	Full
Nuxt.js	Full
Hash-based routers	Not supported

Limitations

• Hash-based routing not supported (e.g., example.com/#/page)
• Older browsers fall back to AJAX, which can lose final route data
• Network conditions may cause occasional data loss

Metrics & Dimensions

High-Level Metrics

Metric	Description
Visits	Page view from different website or direct link
Page Views	Successful HTTP response with HTML content-type
Page Load Time	Total time required to load the page
Core Web Vitals	Google's user experience metrics

Core Web Vitals

Metric	Description	Rating
LCP (Largest Contentful Paint)	Main content load time	Good/Needs Improvement/Poor
INP (Interaction to Next Paint)	UI responsiveness to interactions	Good/Needs Improvement/Poor
CLS (Cumulative Layout Shift)	Visual stability during load	Good/Needs Improvement/Poor

Note: Core Web Vitals currently only work in Chromium browsers. Safari and Firefox support coming soon.

Additional Performance Metrics

Metric	Description
FCP (First Contentful Paint)	Time to first content render
TTFB (Time to First Byte)	Server response time
First Paint	Time to any visual change

Available Dimensions

Dimension	Description
Country	Visitor's country
Host	Domain of the site's URL
Path	Internal links referring visits
Referer	External links referring visits
Device Type	Desktop, mobile, or tablet
Browser	Chrome, Safari, Firefox, etc.
Operating System	Windows, macOS, iOS, Android, etc.
Site	Website's domain name

Bot Filtering

Enable Exclude Bots filter to remove automated traffic for accurate user metrics.

Dashboard Features

Filtering Data

1. Navigate to Web Analytics
2. Select your website
3. Click Add filter
4. Choose dimension from dropdown
5. Click Apply

Time Range Selection

• Default: Previous 24 hours
• Use dropdown to select preset ranges
• Drag on graphs to select custom periods

Data Breakdown

Below visualizations, view detailed breakdowns by:

• Country
• Device type
• Browser
• Path
• Referrer

Rules Configuration

Creating Rules

Rules control tracking for specific websites or paths:

1. Go to Web Analytics > Manage site
2. Select Advanced options
3. Click Add rule
4. Specify action and hostname/path
5. Click Update

Note: Rules are only available for sites proxied through Cloudflare.

Rule Precedence

Configuration rules take priority over Web Analytics rules. If a configuration rule disables tracking, it overrides any Web Analytics rule enabling it.

Privacy Features

Data Collection

Cloudflare Web Analytics is designed with privacy in mind:

• No cookies stored in browser
• No personal data collected
• No localStorage/sessionStorage access
• No IP address logging
• No fingerprinting techniques

EU Visitor Exclusion

Exclude visitors from EU data centers:

1. Go to Web Analytics > Manage site
2. Enable EU visitor exclusion

Free plan customers have EU traffic automatically excluded.

Query String Handling

Query strings are not logged to avoid collecting potentially sensitive data. UTM parameter support may be added in the future.

GraphQL API

Endpoint

POST https://api.cloudflare.com/client/v4/graphql

Authentication

API Token (Recommended):

curl -X POST https://api.cloudflare.com/client/v4/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

API Key:

curl -X POST https://api.cloudflare.com/client/v4/graphql \
  -H "X-Auth-Email: your@email.com" \
  -H "X-Auth-Key: YOUR_GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

Query Structure

{
  viewer {
    zones(filter: { zoneTag: $zoneTag }) {
      # Dataset and fields
    }
  }
}

Basic Query Example

query {
  viewer {
    zones(filter: { zoneTag: "YOUR_ZONE_ID" }) {
      httpRequestsAdaptiveGroups(
        filter: {
          datetime_gt: "2024-01-01T00:00:00Z"
          datetime_lt: "2024-01-02T00:00:00Z"
        }
        limit: 10
        orderBy: [datetime_DESC]
      ) {
        dimensions {
          datetime
          deviceType
        }
        count
      }
    }
  }
}

Query Variables

{
  "query": "query($zoneTag: String!, $start: Time!, $end: Time!) { ... }",
  "variables": {
    "zoneTag": "YOUR_ZONE_ID",
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-02T00:00:00Z"
  }
}

Common Filters

Filter	Description
datetime_gt	Greater than timestamp
datetime_lt	Less than timestamp
date	Specific date
limit	Maximum results
orderBy	Sort order (e.g., datetime_DESC)

Troubleshooting

Common Issues

Issue	Cause	Solution
CORS errors	Hostname mismatch	Verify hostname matches configured site
No data appearing	Ad-blockers	Use automatic injection for proxied sites
Missing final route	SPA data loss	Expected behavior in older browsers
Automatic setup fails	Cache headers	Use manual JS snippet instead

Ad-Blocker Impact

The JavaScript beacon may be blocked by:

• AdBlock Plus
• Brave browser
• DuckDuckGo extension

Solution: For proxied sites, use automatic injection (edge analytics cannot be blocked).

Hostname Verification

Cloudflare uses postfix matching for hostname validation. Ensure your domain exactly matches the configured analytics site.

Cache-Control Issues

Automatic injection doesn't work with:

Cache-Control: public, no-transform

Solution: Use manual JavaScript snippet installation.

Limitations

Limitation	Details
Account limit	Soft limit of 10 sites per account (contact support to increase)
Single snippet	Only one JS snippet per page
Custom events	Not currently supported
UTM parameters	Not yet supported
Hash routing	Not supported for SPAs
Browser support	Core Web Vitals require Chromium

Best Practices

1. Use Automatic Setup When Possible

For proxied sites, automatic injection provides:

• Ad-blocker resistance (edge measurement)
• No code changes needed
• Automatic updates

2. Place Script Correctly

<body>
  <!-- Your content -->

  <!-- Place beacon just before closing body tag -->
  <script
    defer
    src="https://static.cloudflareinsights.com/beacon.min.js"
    data-cf-beacon='{"token": "YOUR_TOKEN"}'
  ></script>
</body>

3. Verify SPA Compatibility

Before deployment, confirm your SPA uses History API routing (not hash-based).

4. Monitor Core Web Vitals

Regularly check CWV scores and address:

• Poor LCP: Optimize largest content element loading
• Poor INP: Reduce JavaScript execution time
• Poor CLS: Reserve space for dynamic content

5. Use Bot Filtering

Enable bot exclusion for accurate user metrics in production environments.

Integration Examples

React Application

// public/index.html
<!DOCTYPE html>
<html>
<head>
  <title>My React App</title>
</head>
<body>
  <div id="root"></div>
  <script
    defer
    src="https://static.cloudflareinsights.com/beacon.min.js"
    data-cf-beacon='{"token": "YOUR_TOKEN"}'
  ></script>
</body>
</html>

Next.js

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <script
          defer
          src="https://static.cloudflareinsights.com/beacon.min.js"
          data-cf-beacon='{"token": "YOUR_TOKEN"}'
        />
      </body>
    </Html>
  )
}

Vue.js (Vite)

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>My Vue App</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.js"></script>
  <script
    defer
    src="https://static.cloudflareinsights.com/beacon.min.js"
    data-cf-beacon='{"token": "YOUR_TOKEN"}'
  ></script>
</body>
</html>

Google Tag Manager

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js?token=YOUR_TOKEN"
></script>

For SPA with GTM, disable SPA tracking if managing navigation events manually:

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js?token=YOUR_TOKEN&spa=false"
></script>

When to Use This Skill

• Setting up Cloudflare Web Analytics for websites
• Configuring analytics for single-page applications
• Implementing privacy-first analytics
• Querying analytics data via GraphQL API
• Troubleshooting Web Analytics issues
• Monitoring Core Web Vitals performance
• Integrating analytics with modern JavaScript frameworks

Resources

• Official Documentation
• GraphQL API Docs
• Cloudflare Dashboard
• Web Analytics Product Page
• Community Forum