Send Visit Events From Your Cloudflare Website (Using a Worker)

Before You Start

If your website is not already connected to Cloudflare:

For Shopify, Webflow, BigCommerce, HubSpot, and Salesforce Commerce Cloud, follow Cloudflare's O2O setup guides.
For other hosts, follow Cloudflare's general setup guide.

Make sure that the DNS records for each website hostname you want to track, such as example.com and www.example.com, have Proxied (orange cloud) enabled.

Step 1: Create a Worker

Open your domain in your Cloudflare dashboard
In the sidebar, click Workers & Pages under Compute (Workers)
Click the Create application button
Select the Start with Hello World! option
Name the worker (something like known-agents-analytics) and click Deploy
In the top right, click the Edit code button
Paste this code into the worker.js file:

const KNOWN_AGENTS_ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

const REQUEST_HEADER_NAMES = [
    "cf-connecting-ip",
    "user-agent",
    "host",
    "x-forwarded-host",
    "referer",
    "signature",
    "signature-agent",
    "signature-input",
]

const RESPONSE_HEADER_NAMES = [
    "content-type",
]

export default {
    async fetch(request, env, ctx) {
        const startTime = Date.now()
        const response = await fetch(request)
        const duration = Date.now() - startTime
        ctx.waitUntil(trackVisit(request, response, duration).catch(() => {}))
        return response
    },
}

async function trackVisit(request, response, duration) {
    const requestURL = new URL(request.url)
    await fetch("https://api.knownagents.com/visits", {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${KNOWN_AGENTS_ACCESS_TOKEN}`,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            request_path: requestURL.pathname + requestURL.search,
            request_method: request.method,
            response_status_code: response.status,
            response_headers: Object.fromEntries(
                [...response.headers].filter(([headerName]) => {
                    return RESPONSE_HEADER_NAMES.includes(headerName)
                })
            ),
            response_duration_in_milliseconds: duration,
            request_headers: Object.fromEntries(
                [...request.headers].filter(([headerName]) => {
                    return REQUEST_HEADER_NAMES.includes(headerName)
                })
            ),
        }),
    })
}

Navigate to the Known Agents Projects page and open your project
Copy your access token from the Settings page
Back in Cloudflare, swap in your access token where it says YOUR_ACCESS_TOKEN
Click Deploy
Navigate back to your Cloudflare dashboard and select your domain
In the sidebar, click Workers Routes
Click Add route in the HTTP Routes section
Add two routes for your domain, with and without www., ending each with /* (e.g. example.com/* and www.example.com/*). Select the same worker for both
Click Save

Tips

For high-volume websites, reduce requests by sending visits in batches. The REST API accepts multiple visits in one request, and Cloudflare Queues can collect and deliver them in batches. Configure the queue to send up to 100 visits every 10 seconds, whichever comes first.
Strip out any sensitive HTTP headers you don't want to send.

Step 2: Test Your Integration

Navigate to the Projects page
Select your project
Click Settings
Click Send a Test Visit
Click Realtime

If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.