Install
Install on WordPress
A plugin that counts every page request on the server, after WordPress has decided what to serve and before anything is sent, and adds the browser snippet for people. It sees crawlers, AI fetchers and agents that never run JavaScript, which a script tag can't. No cookies.
- Nothing changes for your visitors. The event is sent without waiting for a reply; building it takes well under a millisecond.
- Never breaks your site. Without a DSN, or if Punchline is unreachable, pages are served as usual.
- Agents' signatures come through. When an agent signs its request (Web Bot Auth), the plugin passes the signature along, so it's verified like it would be at an edge install.
If the site sits behind Cloudflare, the Cloudflare Worker sees every request including cached pages and can serve agents markdown. The plugin is for sites where that isn't an option.
Install
You'll need your PUNCHLINE_DSN value (Site settings → Install in your dashboard).
- Download
punchline-analytics-wordpress.zip. - In WordPress, Plugins → Add New → Upload Plugin, choose the zip, install and activate.
- Settings → Punchline Analytics: paste the DSN and save. Leave Add the browser snippet on.
- In your Punchline dashboard, under Site settings → Allowed hosts, list the site's hostnames (
example.comandwww.example.comif both serve pages), so the snippet is accepted. - Check it's working. Visit a few pages. They appear in the dashboard within about a minute; Doctor → Site check says when the last page view arrived.
WooCommerce purchases
With WooCommerce active, the plugin also counts paid orders as purchase events, so you can see how many orders agents placed and how many people did, and what each was worth. It's on by default; turn it off under Settings → Punchline Analytics → WooCommerce purchases.
- Once per order, when the payment completes, or when an order paid by bank transfer or cash on delivery moves to processing or completed.
- Tied to the visit it came from. WooCommerce records the shopper's address and browser at checkout; the plugin sends those with the order, and Punchline uses them in memory to find the visit and its label, exactly as for page views. An order an agent placed counts as the agent's.
- What's sent: the total, the currency and the number of items. Never names, emails, addresses or what was bought.
- No API key or paid plan needed. Purchases go to your collector with the same DSN as page views. They show under Events and can be goals, like any event.
An order paid more than half an hour after checkout (a bank transfer a day later) is still counted, but not tied to a visit.
Works with WooCommerce's order storage (HPOS) and the block checkout.
Page caches
WP Super Cache, W3 Total Cache, WP Rocket and most hosts' caches serve cached pages without running WordPress, so this plugin doesn't see those requests:
- People on cached pages are still counted, by the browser snippet. Each page load is counted once: the plugin marks the responses it counted, and the snippet skips them.
- Agents that fetch a cached page are not counted. The first fetch of a page after the cache clears is; later ones aren't.
If most of your pages are cached and agent traffic is what you came for, put the Cloudflare Worker in front of the site instead. The plugin can stay for the snippet.
Visitor addresses behind a proxy
The plugin reads the visitor's address from the connection, or from Cloudflare's CF-Connecting-IP header when present. If the site is behind another proxy or load balancer, turn on This site is behind a proxy in the plugin's settings so it reads X-Forwarded-For. Only do that when every request reaches WordPress through the proxy; otherwise anyone could claim an address, and an agent could claim an operator's.
What's sent
The same as the other installs: the host, the path, utm_* values and the query string with credential and personal-data values redacted and emails removed, the referrer's host, the Accept header, which browser headers were present (never their values), Web Bot Auth signature headers when an agent sent them, and the IP address and user agent. The collector uses the address and user agent in memory for people, never storing them, and keeps them with the visit for agents. See Privacy.
What isn't tracked: the admin, logins, the REST API, AJAX, cron, previews, and requests for files.
Troubleshooting
- Nothing arrives. Check the DSN saved without an error on the settings page (it must start with
https://and contain<site-id>:<secret>@). Then check outbound HTTPS from the server isn't blocked: the plugin posts to the collector host in the DSN. - Only people show up. The site is probably fully cached; see above.
- The snippet is refused. Doctor → Site check names the host to add under Allowed hosts.
Ask the docs
Answers come from these docs only, written by Claude (Anthropic). Your question is sent to answer it, and isn't stored.