Skip to content
qiayuePublic

About

PVUV.ai : Privacy-friendly, self-hosted web analytics with built-in invalid-traffic detection and AdSense protection. Runs on Cloudflare Workers + D1.

Resources

Contributing

Security policy

Stars

101 stars

Watchers

2 watching

Forks

Repository files navigation

pvuv.ai

Privacy-conscious web analytics with built-in invalid-traffic detection and ad protection. Use the hosted service, or run the whole thing yourself on Cloudflare.

License: MIT Release: v0.1.0 Runs on Cloudflare

中文说明 / Chinese: README.zh-CN.md · Full build spec: PROJECT_PLAN.md

pvuv.ai is a lightweight analytics platform that runs on Cloudflare's edge. Beyond counting PV/UV, it scores every hit for authenticity, spots invalid traffic that only reveals itself in aggregate, and can gate ad code so it loads only for traffic judged trustworthy — helping protect ad accounts from invalid-traffic penalties.

Two ways to use it

Not sure? Start hosted. You can move to self-hosting later — it is the same product, and the snippet on your site is the only thing that changes.

Hosted — pvuv.ai Self-hosted — this repo
Getting started Sign in with Google, add the snippet 4 commands, ~10 minutes
You need nothing a Cloudflare account (Workers Paid, $5/mo) and a domain on it
Upgrades & uptime handled for you you run git pull and redeploy
Where the data lives on our servers only in your own Cloudflare account — no third party, ever
Tuning detection product defaults every signal weight and threshold is yours to change
Licence — MIT: use it, modify it, sell it. No strings.

→ Hosted: go to pvuv.ai, sign in with Google, and skip the rest of this README. → Self-hosted: read on, then jump to Before you start.

Status. v0.1.0 is the first open-source release — see CHANGELOG.md. It is pre-1.0: interfaces and schema may still change between minor versions, and every schema change ships as a D1 migration with upgrade notes in DEPLOY.md.


Why

Most self-hosted analytics tools count traffic but treat every request as real. Sites that monetize with ad networks are exposed to invalid-traffic penalties they can't see coming. pvuv.ai treats traffic quality as a first-class metric: it collects the usual analytics and a layered authenticity signal, so you can tell clean traffic from bots, understand where bad traffic comes from, and act on it.

Features

Full-dimension analytics

  • Multi-site and multi-subdomain, per-page PV/UV
  • Referrers, full UTM set, and all click/tracking params (gclid, fbclid, ttclid, msclkid, ref, …)
  • GA4-style channel groups, first-touch source/medium/campaign per visitor
  • Bounce rate (engagement-based, GA4-style), true dwell time, scroll depth, per-visitor journeys
  • Custom events and goals with revenue (recorded in USD; other currencies are stored but not yet converted)
  • Funnels with segment breakdown, drop-off drill-down, friction signals and saved funnels
  • Core Web Vitals, plus frustration / JS-error / form-abandon signals
  • identify() to tie a visitor to your own user id
  • Public read-only share links for a site's dashboard

Invalid-traffic detection (three layers)

  • Client signals — headless/automation traits, environment contradictions, canvas render probes, a honeypot link, pointer dynamics
  • Request & session features — transport fingerprint, declared AI agents, inter-page timing, path patterns, scroll vs pointer interaction, session drift
  • Population statistics (daily batch) — network/transport clusters and one-shot farms, graph propagation, conversion-timing analysis, concentration shifts and baseline anomalies
  • Every event carries a 0–100 score, a verdict (clean/suspect/bot/crawler), and a bit-flag record of which signals fired

Ad protection (optional)

  • Progressive verdict: fast first-page decision, then accurate blocking from the second page onward
  • Loads ad code only for trustworthy traffic; never modifies the ad network's script (decides whether to inject only)
  • Fail-open by design — any error defaults to loading ads, never costing you revenue
  • Per-site owner-controlled thresholds with a shadow (record-only) mode to preview impact before enforcing

AI-powered analysis (optional)

  • On-demand written reports per site: data anomaly → attribution → actionable recommendations, using any OpenAI-compatible endpoint or the Anthropic API that you configure

Open by default

  • Read-only REST API, an MCP server so your own chatbot can query your traffic, and a CLI — one revocable, scopeable token for all three (docs/API.md)
  • Console in 7 languages (English, 中文, 日本語, 한국어, Deutsch, Français, Español), switchable client-side
  • One-click export of everything the dashboard shows, as JSON
  • Configurable D1 retention with a storage panel, so a busy site stays inside D1's limits
  • Optional crawler categorisation (search vs AI-training vs SEO vs ad verification) from an imported public bot directory

Architecture

browser (f.js)
  → in.pvuv.ai/in   ingest Worker: validate + server-side enrichment + realtime scoring
  → Cloudflare Queue
  → consumer Worker: batch-write D1 events, update sessions/profiles
  → Cron (hourly)   rollup pre-aggregation tables
  → Cron (daily)    population analysis → re-verdict + KV blocklist ──┐
                                                                      │ loops back to
  api.pvuv.ai/v1    query API (dashboard / ranking / AI)             │
  pvuv.ai           console (dashboards, traffic quality)   in.pvuv.ai/v ←┘ fast verdict

Hostnames above are the reference deployment. A self-hosted install defaults to analytics.<domain> (console, which also serves f.js), in.<domain> (ingest) and api.<domain> (query API) — npm run setup asks, and every host can be overridden.

Domain split — the ingest host that gets embedded on measured sites is kept separate from the internal ones (api, console), so if an exposed host ever hits a blocklist, dashboards and queries are unaffected. For the strongest isolation, serve the SDK first-party through the optional workers/proxy. See PROJECT_PLAN.md §1.

Tech stack

Cloudflare Workers (ingest, consumer, api, console, cron, optional proxy) · D1 (SQLite, monthly-partitioned events) · Queues (spike buffering) · KV (blocklist, config cache) · Cron Triggers (rollups, batch analysis, retention). No external database, no server to run.

Before you start

Self-hosting needs three things. Check all three now — the third one is the usual surprise, and it is easier to discover here than halfway through an install:

  • Node.js 22+ on your machine (required by wrangler 4)
  • A domain already added to Cloudflare (any plan). You do not have to move your website — only the domain needs to be on Cloudflare's DNS
  • Workers Paid plan — $5/month. Not optional: the ingest pipeline uses Cloudflare Queues, which the free plan does not include

Everything else — the database, the KV stores, the queues, DNS records, TLS certificates — is created for you.

Only want to try it? The hosted service needs none of this.

Install

Full step-by-step guide: DEPLOY.md (中文: DEPLOY.zh-CN.md). The short version:

git clone https://github.com/qiayue/pvuv.ai.git && cd pvuv.ai
npm install
npx wrangler login
npm run setup

npm run setup does the rest: creates the D1 database, KV namespaces and queues, fills in every config placeholder, points the routes at your domain, applies the migrations, builds the SDK and deploys all five workers. It is safe to re-run — completed steps are skipped and an already-configured file is never overwritten. Add --dry-run first to see exactly what it would do.

Your domain is asked for once, at the start, and written everywhere it is needed. DNS records and certificates are provisioned automatically (the workers use Cloudflare Custom Domains), so the only step that cannot be automated is creating a Google/GitHub OAuth app — console login is OAuth-only. It prints that step last, with your callback URLs filled in; DEPLOY.md walks through it.

The domain must already be added to your Cloudflare account, and each hostname must be free — a worker serves its host entirely.

Non-interactive (CI, scripted installs):

npm run setup -- --domain example.com --admin you@example.com

Then sign in at your console domain with Google/GitHub (your email must be in ADMIN_EMAILS), register a site, and embed the snippet it prints. Details, OAuth setup, DNS notes, verification, and troubleshooting: DEPLOY.md.

Add it to a site

Register a site in the console to get a site_id, then embed:

<script defer src="https://analytics.example.com/f.js"
        data-site="YOUR_SITE_ID"
        data-api="https://in.example.com"
        data-adguard="balanced"
        data-adclient="ca-pub-xxxxxxxxxxxxxxxx"></script>

data-api is your ingest host (or the first-party reverse proxy, see PROJECT_PLAN.md §12). Optional attributes: data-spa="true" (SPA route tracking), data-exclude="/admin/*", data-sensors="off" (disable mobile-sensor signals for compliance).

Always keep data-api — without it the SDK falls back to the reference ingest host. The snippet the console generates already has the right src and data-api for your deployment, so copying it is the safest route.

Your first week

Ad protection ships off, on purpose. Blocking ad code for real people costs real money, so the product is built to make you look before you enforce.

Day 1 — confirm data is arriving. Open the console, click Self-check, then watch the realtime count at the top of your site's dashboard while you load your own page.

Days 1–7 — just watch. Learn what normal looks like for your site before changing anything:

  • Traffic quality shows the clean / suspect / bot / crawler split and which detection signals actually fired.
  • The traffic-health strip shows each monitored ratio and how far it is from its alert threshold — so you see a number climbing before it becomes a problem.
  • The chart's invalid-traffic band tells you whether bad traffic is one short burst or spread across the day. Those mean very different things.

Week 2 — preview what ad protection would do. The Ad protection tab estimates, for each tier, how many pageviews it would block and the resulting false-positive rate — computed from your own recorded traffic. No setting has to change to see this, and it is available from the moment you have data.

Then enforce. Pick the tier whose false-positive rate you can live with — balanced is usually the answer — and switch it on. You can go back to off at any time.

Shadow mode is a separate safety net for the other order of operations: if you enable protection when creating a site, it records decisions while still loading ads normally for the first adguard.shadow_days (7 by default), then begins enforcing. A site created with protection off has nothing to shadow — use the tab's estimate above instead.

Once it is running, useful next steps: create an API token to query your data from a chatbot or the CLI (docs/API.md), and tune the signal weights in config.local.toml if your traffic has quirks the defaults misjudge.

Optional, once you're comfortable — see what the script never saw. Every number above comes from the tracking script, so all of it is limited to visitors whose browser ran JavaScript. AI crawlers and scrapers fetch your HTML and leave; they never run a script, so they are absent by construction. Cloudflare counted them anyway. Paste a read-only Cloudflare API token into ⚙ settings and the nightly job pulls those request counts, so the dashboard can show the gap:

Edge HTML requests   12,480    ← what Cloudflare served
Browser pageviews     2,773    ← what the script reported
Gap                   9,707    ← fetched HTML, never ran JS

Skip it and everything works exactly as it does today — the panel simply stays hidden. Setup is two read-only permissions and one paste: DEPLOY.md → Cloudflare edge requests.

Configuration

Scoring weights, verdict thresholds, and the blocklist are tunable and deployment-private. config.example.toml ships example defaults; copy it to config.local.toml (gitignored) and tune privately. The engine reads weights from config — nothing is hardcoded — so you can adjust detection without exposing it to fraudsters. See PROJECT_PLAN.md §21.

API, MCP server & CLI

Read your data from anywhere: a REST API for integrations, an MCP server so your own chatbot can answer questions about your traffic, and a CLI for terminals and cron jobs. All read-only, all sharing one credential.

Create a personal API token in the console (⚙ → API tokens) — scoped to one site or all of yours, individually revocable, stored only as an HMAC.

export PVUV_API_URL=https://api.example.com   # your API host
export PVUV_TOKEN=pvuv_…

curl -H "Authorization: Bearer $PVUV_TOKEN" "$PVUV_API_URL/v1/sites"
node cli/pvuv.mjs overview <site_id> --period 7d

The MCP server and CLI are dependency-free single files, so nothing extra is installed around a token. Full reference: docs/API.md.

External ranking API (optional)

An external ranking/scoring system can pull a cross-site, clean-traffic leaderboard in one call, authorized with the server-side API_TOKEN secret (not set by npm run setup — add it with npx wrangler secret put API_TOKEN -c workers/api/wrangler.toml if you need this):

curl -H "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/ranking?period=30d"

Returns each active site with clean (bot/crawler/suspect-excluded) pageviews split into internal (mutual visits referred by another site in the same deployment) and external traffic. The default score is external clean pageviews, so mutual visits between your own sites can't inflate the ranking; every field is exposed so an external system can apply its own formula. Owners also see this as a "Site ranking" table in the console. See PROJECT_PLAN.md §14.

Editions

pvuv.ai is open core — see Two ways to use it for choosing between them:

  • This repository — the self-hosted edition — is MIT-licensed. Use it, modify it, run it commercially, fold it into a closed product. No copyleft, no attribution requirement, no strings. Use it without a second thought.
  • The hosted service at pvuv.ai (managed accounts, upgrades, support) is run by the author and is not part of this repository. The two do not overlap or conflict — this open-source edition is complete and fully functional on its own, with no feature held back and no phoning home.

Attribution (optional)

The shipped default homepage carries a small "Powered by pvuv.ai" footer linking back to the project — on the deployed instance's homepage only (dashboards and inner pages have no links, and nothing is ever injected into the sites you measure). It's a courtesy, not a requirement: MIT imposes none. Keep it if you'd like to support the project, or remove it freely — provide your own workers/console/public/home.html (served verbatim, with no footer added) or edit the default page. A star on GitHub is always appreciated. 🙏

The default homepage is intentionally sparse — it is meant to be customized. Thousands of deployments sharing identical landing copy would only create duplicate-content noise in search engines.

Privacy & compliance

pvuv.ai is designed to minimize what it stores:

  • IP is stored only as a truncated hash (+ /24 segment hash), never in plaintext.
  • Device fingerprints are stored as hashes and conclusions only — never raw values — and are used solely for authenticity scoring, not cross-site visitor profiling.
  • Mobile-sensor signals are coarse booleans only (no raw streams, no sensor fingerprint) and can be turned off.

Deployer responsibility: in GDPR/ePrivacy jurisdictions, fingerprinting and sensor signals may require user consent. The project ships data-minimizing defaults and opt-out toggles; each deployer is responsible for compliance in their own jurisdiction. See PROJECT_PLAN.md §16.

Roadmap

Milestone Scope Status in v0.1.0
M1 (first deployable) SDK + ingest + fast verdict + D1 schema + minimal console (PV/UV, sources, top pages, traffic-quality overview) ✅ Done
M2 Sessions/dwell/bounce, full UTM, rollup acceleration, population analysis + blocklist loop, shadow mode, reverse-proxy option 🟡 Mostly — all done except fingerprint-based clusters and the fingerprint blocklist, which stay dormant until the expensive client checks ship
M3 identify + custom events + revenue + funnel attribution, distribution tests + baseline anomalies 🟡 Partly — events, revenue, funnels and baseline anomalies are done; currency conversion, cross-device merge, attribution models and statistical distribution tests are not yet
M4 AI reports, full anti-fraud, external ranking integration, human-review UI 🟡 Partly — on-demand AI reports and the ranking API are done; scheduled reports, WebGL/canvas fingerprinting with cross-site clusters, and the human-review UI are not yet

Release history: CHANGELOG.md. Full details in PROJECT_PLAN.md.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Please read the build spec first so proposals fit the architecture.

Security

Found a vulnerability? Please report it privately — see SECURITY.md. Do not open a public issue for security reports.

License

MIT. Do whatever you want — self-host, modify, redistribute, or use it commercially — with no obligation to open your changes and no attribution requirement. The separately-offered hosted multi-tenant SaaS edition is licensed on its own terms and is not covered by this repository.

About

PVUV.ai : Privacy-friendly, self-hosted web analytics with built-in invalid-traffic detection and AdSense protection. Runs on Cloudflare Workers + D1.

Resources

Contributing

Security policy

Stars

101 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages