Cloudflare Web Analytics

Cloudflare Web Analytics

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

Quick Reference

Key Features

Setup Methods

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

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

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

Core Web Vitals

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

Additional Performance Metrics

Available Dimensions

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

Troubleshooting

Common Issues

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

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