# 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](https://punchlineanalytics.com/docs/install-cloudflare) sees every request including cached pages and can [serve agents markdown](https://punchlineanalytics.com/docs/edge-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).

1. **Download** [`punchline-analytics-wordpress.zip`](https://punchlineanalytics.com/downloads/punchline-analytics-wordpress.zip).
2. In WordPress, **Plugins → Add New → Upload Plugin**, choose the zip, install and activate.
3. **Settings → Punchline Analytics**: paste the DSN and save. Leave *Add the browser snippet* on.
4. In your Punchline dashboard, under Site settings → Allowed hosts, list the site's hostnames (`example.com` and `www.example.com` if both serve pages), so the snippet is accepted.
5. **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](https://punchlineanalytics.com/docs/events-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](https://punchlineanalytics.com/docs/install-cloudflare) 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](https://punchlineanalytics.com/docs/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.
