Home › Guide

How to use PVUV.ai

Everything a site owner needs, in order: create your account, add your sites, install the tracking code, read the dashboard, measure goals and funnels, share what you want to share, and let your AI assistant work with your numbers.

Guide · Updated October 2026 · ~10 min read

1. Your account

Go to Sign in and choose Google or Web.Cafe. Your account is created the first time you sign in — there is nothing else to fill in.

  • Every site you add belongs to this account. Your sites, funnels and tokens appear only in your dashboard; other users never see them.
  • Each sign-in method is its own account. Signing in with Google and with Web.Cafe gives you two separate accounts, even with the same email address — always use the same one.
  • One account can hold up to 100 sites.

Bind both sign-ins. Under ⚙ Settings → Sign-in methods, a Google account can bind Web.Cafe and a Web.Cafe account can bind Google; afterwards either sign-in opens the same account. If the account you bind already has sites or API tokens, you are asked to confirm, and they move into this account — this cannot be undone.

2. Add a site

On your sites page, use Add a site:

  1. Domains — the site’s host names, comma-separated (for example example.com, www.example.com, blog.example.com). The tracking code only accepts data from these domains.
  2. Site name — what you see in the dashboard.
  3. More options: Timezone (days and reports follow it; it can’t be changed later), Ad protection mode (leave it Off for now — see Ad protection) and the engagement threshold (seconds before a visit counts as engaged, 15 by default).

If you add a domain you already track, you are taken to that site instead of getting a duplicate.

3. Install the tracking code

After creating the site you get a snippet with your site ID filled in. Paste it into the <head> of every page (in most frameworks: the shared layout):

<script defer
  src="https://www.pvuv.ai/f.js"
  data-api="https://in.pvuv.ai"
  data-site="YOUR_SITE_ID"></script>

Open your site once: the visit appears in the dashboard’s realtime count within seconds.

Options

  • Single-page apps (React, Vue, Next.js…) are tracked automatically — each change of path is a pageview. data-spa="true" also counts query-string changes; data-spa="false" turns route tracking off.
  • data-exclude="/admin/*" skips pages you don’t want measured.
  • data-sensors="off" disables the coarse mobile-sensor signals.
  • data-downloads="off" stops automatic file-download events.

Not seeing data? Check that the page’s domain is in the site’s domain list, that the script isn’t blocked by your Content-Security-Policy, and that you opened the page after installing.

4. Read the dashboard

Open a site from your sites page. The top bar holds the site switcher, the online now count, filters and the period.

  • Online now counts people seen in the last 5 minutes; click it to switch to 10 or 30 minutes. The label always says which window you are looking at.
  • Visitors counts people only — bots and crawlers are left out, and the card shows how many were. Pageviews, Sessions, Bounce rate, Visit duration and Human share sit beside it; each compares with the previous period.
  • Below: the chart, then Sources (or channels), Pages (entry, exit, 404), Locations, Devices, Campaigns (UTM) and Goals.
  • Click any row to filter the whole dashboard by it; + Filter adds filters with is, is not or contains.

The tabs: Overview, Funnel (funnels and tracking health), Suspicious (individual high-scoring visitors and why), Ad protection, Web Vitals (real-user loading speed per page) and AI report. ⋯ → Visitor journeys replays what a single visitor did, page by page.

5. Bots, crawlers & fakes

Every visit gets a score from 0 to 100 and a verdict:

  • Clean — a person. Suspect — counted, but flagged (shown amber: uncertain, not confirmed).
  • Bot — automated, left out of your visitor numbers.
  • Crawler — a search engine, link preview or AI crawler, reported on its own. The Crawlers by category panel names each one (Googlebot, Bingbot, GPTBot, facebookexternalhit…) and checks it against the IP ranges its operator publishes.
  • Fake crawler — something that calls itself Googlebot or GPTBot from an address outside that operator’s ranges. It is counted as a bot and shown on its own in the traffic-quality chart, the filters and the visitor list.

The traffic-health strip shows each ratio the alerts watch and how far it is from its threshold, so you see a number climbing before it becomes a problem.

6. Goals, events & revenue

Any event other than a pageview is a goal. Three ways to send one:

No code

<button data-pvuv-event="signup_click" data-pvuv-plan="pro">Sign up</button>

From JavaScript

window.pvuv && window.pvuv('event', 'purchase', { revenue: 29, currency: 'USD', plan: 'pro' });
window.pvuv && window.pvuv('identify', internalUserId);   // after sign-in; an opaque id, never an email
window.pvuv && window.pvuv('set', { variant: 'b' });       // a property on everything that follows

From your server

Signups, payments and other things your backend knows for certain can be sent with POST https://api.pvuv.ai/v1/sites/<site_id>/events and a server-reporting token (see API tokens). Pass the visitor’s _pv_id cookie or the id you gave to identify, and the event joins that visitor’s journey and funnels. Ad blockers and closed tabs can’t lose it.

Outbound clicks, file downloads and 404 pages are recorded automatically. Revenue in other currencies is converted to USD.

7. Funnels & tracking health

In the Funnel tab, build a funnel from steps — a page (/pricing, /docs/*) or an event (signup). Each step can:

  • accept alternatives (or: any of several pages or events);
  • require property conditions (for example plan is pro);
  • sit inside a time window (the whole funnel within 30 minutes, say).

Break a funnel down by source, device or a property to see where each group drops off, then Save funnel. Suggested funnels are built from the events your site already sends.

Tracking health, under the funnel, compares what your site actually sends with its tracking plan: planned events that never arrive, events nobody planned, missing properties, funnel steps that never fire and server events that couldn’t be tied to a visitor.

Contests

Sometimes there is a traffic contest: sites compete on human visitors and human pageviews over set dates. Open contests appear on your sites page under Contests — pick a site and Enter this site. Depending on the contest, an entry is either approved at once or reviewed by an administrator first; once approved, the site appears on the public contest page.

An administrator can remove an entry that breaks the contest rules, with a reason that you see next to the entry on your sites page. A removed site cannot enter the same contest again unless an administrator restores it.

Entering a contest needs a bound Web.Cafe account (or one that signs in with Web.Cafe), so the organisers know which member each site belongs to; bind it under ⚙ Settings → Sign-in methods.

The public page shows a partly hidden domain and your nickname, never your site ID. Set the nickname under ⚙ Settings → Public nickname; without one, your Web.Cafe nickname is used. A Google account name is never shown. Bots, crawlers and fake crawlers never count. You can withdraw an entry at any time.

The full leaderboard — every site's figures, all rankings and bot share — is visible to participants (owners of an approved site) only. Everyone else sees the top three by human visitors and by human pageviews; the rest is masked.

8. Share & export

  • ⋯ → Share link creates a read-only public dashboard for one site. Anyone with the link can view it; turn it off to revoke it.
  • ⋯ → Embed code puts that dashboard in another page.
  • ⋯ → Download data exports what the dashboard shows.

9. Connect your AI

On a site, ⋯ → Connect AI. Choose what it may do — read this site’s analytics, or read, and also save funnels and create server reporting tokens — then Create connection. The dialog shows the exact setup for Claude Code, Claude Code (web), Cursor and Codex; any other MCP client works with the same address and token.

Then just ask, for example:

  • “Where do visitors drop off between the pricing page and signup this month?”
  • “What changed compared with last week, and why?”
  • “How much of yesterday’s traffic was bots, and from where?”
  • “Check our tracking against the plan and fix what’s missing in this repository.”

A connection for all your sites (create it under ⚙ Settings → API tokens) can also list your sites and add a new one from a domain — handy when your AI sets up analytics for a new project.

The token is shown once. Keep it out of your repository: the setup instructions put it in your user configuration or an environment variable.

10. API tokens

⚙ Settings → API tokens on your sites page lists every token and lets you create one with a scope (one site, or all your sites) and a purpose:

  • AI assistant / CLI — read only.
  • AI assistant — read, edit funnels, create sites.
  • Server reporting — server events and crawler hits only; it can’t read anything.

Tokens are shown once, stored only as a hash, and can be revoked at any time. The same token works for the MCP server, the REST API and the command-line tool — see the API reference.

11. Report AI crawlers (optional)

ChatGPT, Perplexity and Claude fetch your pages without running JavaScript, so the tracking code never sees them. Your server can report those fetches; the dashboard’s AI assistants & crawlers panel then shows which pages each assistant read, verified against its published IP ranges, and the visitors it sent back. It takes three steps:

  1. Create a token. ⚙ Settings → API tokens, scope: this site, purpose: Server reporting. It can report crawler hits and read nothing. Keep it on the server as a secret, e.g. PVUV_INGEST_TOKEN, together with PVUV_SITE = your site ID (the id= in the dashboard’s address).
  2. Add the reporting code. The easiest way is to give your AI coding assistant (Claude Code, Cursor, Codex…) this request in your site’s project: 
    Follow https://api.pvuv.ai/docs/crawler-sync.md to add pvuv.ai crawler reporting to this site.
Site ID: YOUR_SITE_ID. The token is in the PVUV_INGEST_TOKEN environment variable.
    The guide has ready code for Next.js (Vercel or self-hosted), Cloudflare Workers / Pages, Node / Express and other servers. The code reports after the response is sent, so it never slows down or breaks your pages.
  3. Deploy and check. After deploying, request one of your pages as a crawler: 
    curl -A "ChatGPT-User/1.0" https://your-site.com/
    Refresh the dashboard: the panel shows the hit as a fake ChatGPT-User — correct, because it came from your computer, not OpenAI’s addresses. Real assistant visits then show up as verified.

If you have connected an AI assistant over MCP, you can also just ask it to “set up crawler reporting for my site” — it creates the token and follows the same guide.

12. Ad protection (optional)

Ad protection loads your ad code only for traffic judged trustworthy. It ships off:

  1. Watch for a week to learn what normal looks like for your site.
  2. Open the Ad protection tab: it estimates, for each tier, how many pageviews would be blocked and the false-positive rate — from your own traffic.
  3. Pick a tier (Balanced is usually right) and add data-adguard and data-adclient to the tracking code. A new protection setting first runs in shadow mode — recording decisions while ads still load — before it enforces.

It fails open: if anything goes wrong, ads load.

13. Language, theme & timezone

  • Language: English, 中文, 日本語, 한국어, Deutsch, Français and Español, from the language menu.
  • Theme: follows your system, or pick Light or Dark — next to the language menu (on a site, under ⋯).
  • Timezone: your account’s default lives under ⚙ Settings; each site keeps the timezone it was created with.

14. Privacy & consent

IP addresses are stored only as a truncated hash, device fingerprints only as hashes and conclusions, and crawler addresses are checked and never stored. On your website, first-party cookies hold the visitor identity, session and first-touch attribution, and localStorage may hold a visitor identifier. In GDPR/ePrivacy jurisdictions this may need visitor consent — as the site owner, that is your call; data-sensors="off" reduces what is collected. See the Privacy Policy.

FAQ

Why are my numbers lower than Google Analytics?

Visitors here are people only: bots, crawlers and fake crawlers are counted separately rather than mixed in. Ad blockers, consent settings and different session rules also make any two tools differ.

Can someone else track my domain?

Another account can add the same domain, but each account sees only the data of its own site, and data is accepted only from the domains listed on that site.

How do I remove a token or stop sharing?

Revoke the token under ⚙ Settings → API tokens; turn off the share link from ⋯ → Share link.

Is it free?

Yes — analytics, funnels, bot detection, crawler checks and ad protection, on up to 100 sites. Only the optional AI reports are a paid add-on. You can also self-host the open-source single-tenant edition.