Wispstat

Official documentation · MIT open source

Wispstat docs

Cookie-free analytics on your Cloudflare Worker. Pageviews, outbound links, downloads, and form submits are automatic; goals and client shares are opt-in.

Install

Deploy the Worker (README Deploy button or npm run setup), claim with SETUP_TOKEN, then add a site with one domain root and paste the tracker on hosts you want measured.

  1. Create the site Overview → Add a site. One domain (e.g. example.com) — that host and all subdomains under it.
  2. Paste the snippet From Settings or the create response. Before </body> is fine. 
    <script defer
  src="https://YOUR_WORKER/ws.js"
  data-site="s_yourSiteIdHere"></script>
  3. Confirm Live Open the site → Live. You should see pageviews after a hit.

data-site is public HTML. It is an identifier, not a secret.

What logs by default

Pageviews plus light auto-events. Disable autos with data-auto-events="false".

  • Pageview on load (unless data-auto="false")
  • SPA route changes via data-spa="auto"
  • Outbound · downloads · form submit (never field values)
  • Heat + scroll depth (off with data-heatmap="false")
  • Signup / purchase / custom goals — fire wispstat('event', …) yourself

Optional: data-respect-dnt, data-exclude, data-mask, data-hash-mode, data-file-types.

Attribution

First pageview of a load captures utm_*, or ref/via, plus external referrer. That becomes same-day first-touch. CRM handoff: wispstat('attribution').

Custom events

Names ≤64 chars, charset [a-z0-9_:.-]. Pair with a Goal of kind event for conversion rates.

  • wispstat('pageview') Manual pageview Useful if auto pageviews are off.
  • wispstat('event', 'signup') Named event Pair with a Goal for conversion rates.
  • wispstat('event', 'purchase', { value: 49.9 }) Event + value Revenue in the site currency.

Share with a client

Site → Settings → Share with a client. Read-only summary via link or iframe. No login for them. Treat the URL like a password; revoke when done.

Security

  • Visitors: no cookies in default mode; daily hashed IDs; one domain root + subdomains.
  • Forms: submit events never include field values.
  • You: email/password on your Worker; keep SETUP_TOKEN private.
  • Clients: share links only see that site’s rolled-up numbers.

Data budget

Overview estimates Cloudflare Free usage today (writes and requests vs ~100k/day caps). Counts rise with real pageviews and events only.