Docs menu

Operate

Real visitor speed

See how fast your pages are for the people visiting them, by device, country and page, measured in their own browsers. One script tag, no cookies.

Explain it

CLI's other speed numbers say how quickly your server answered. That's only part of the wait: a visitor on a phone, far away, on a slow connection, waits for much more than the server.

Real visitor speed measures what people actually waited for, in their own browsers:

  • Main content shown: how long until the biggest thing on the page appeared.
  • Reacts to taps: how long the page took to respond when someone tapped or clicked.
  • Layout jumps: how much things moved around while loading.
  • First byte: how long until anything came back from your app.

You see what 3 in 4 visits got or better (the yardstick Google uses), with a simple rating: Good, Could be faster or Slow. It's broken down by phones, tablets and computers, by country, and by page, so you can see that, say, your product pages are slow for visitors in Brazil.

It needs one script tag on your pages. It sets no cookies and sends nothing that identifies a person: each visit sends its numbers once, with the page and country, and that's all.

How to do it: open an app, go to Settings, find Real visitor speed and press Turn on visitor speed. Copy the script tag into the <head> of your pages and deploy. Numbers show up as people visit.

You can then make a promise from it: "75% of visits show the page within 2.5 seconds".

Turn it on

API
PUT /v1/services/:id/visitor-speed
{"enabled": true}

The answer includes snippet:

html
<script src="https://api.clicloud.app/v1/speed.js" data-key="spd_…" defer></script>

The key is public (it only lets browsers send measurements for this app). {"enabled": false} turns it off: the key stops working and the measurements are deleted.

What the script sends

The script (about 1.5 KB, no dependencies) reads the browser's Performance APIs: largest contentful paint (LCP), interaction to next paint (INP, the slowest interaction), cumulative layout shift (CLS, the largest burst), time to first byte (TTFB) and first contentful paint (FCP). When the page is hidden or closed, it sends one beacon to POST /v1/speed/<key> with those numbers, the page path, the window width and the connection type.

CLI adds the country from the edge's header (CF-IPCountry and similar) and a device class from the user agent: phone, tablet or computer. Numbers in paths become :n (/products/123 → /products/:n). Bots and crawlers are dropped. Nothing else is stored, and measurements are kept for 30 days. Each app accepts up to 1,200 beacons a minute.

Reading it

API
GET /v1/services/:id/visitor-speed?hours=24

metrics has, for each of lcp, inp, cls, ttfb and fcp: the 75th percentile (p75), its rating, the share of good visits and the sample count. byDevice, byCountry (top 12) and byPage (top 10 by visits) give the LCP 75th percentile for each. Ratings use Google's Core Web Vitals thresholds:

MeasureGoodPoor
LCP≤ 2.5 s> 4 s
INP≤ 200 ms> 500 ms
CLS≤ 0.1> 0.25
TTFB≤ 800 ms> 1.8 s
FCP≤ 1.8 s> 3 s

In promises

JSON
{"promise": {"visitorLoadMs": 2500, "visitorPercent": 75, "guard": "warn"}}

counts visits whose LCP was over 2.5 s against a 25% allowance over the promise's window, like the other promises.