Install Spurn on WooCommerce
The Spurn plugin adds the tag to every page, sends a server hit when a paid click lands, and reports WooCommerce orders as conversions. None of it slows a page down.
Before you start#
- WordPress 6.0 or later, PHP 7.4 or later, WooCommerce 7.0 or later.
- Permission to install plugins (an administrator account).
- Your site's keys from Spurn: Sites, then your site, then the Keys tab. You need the public key (
sp_pub_…) and a secret key (sp_sec_…). A secret key is shown once, when you create it. - The plugin zip,
spurn-wordpress.zip, from your site's Install tab in Spurn.
Install the plugin#
- In WordPress, go to Plugins, then Add New Plugin, then Upload Plugin.
- Choose
spurn-wordpress.zipand click Install Now. - Click Activate.
Add your keys#
- Go to Settings, then Spurn (or click Settings under Spurn on the Plugins screen).
- Under Site keys, paste the Public key and the Secret key.
- Under Advanced, set Visitor IP header (see below). Leave Spurn address as
https://spurn.io. - Click Save changes.
- Click Test connection. You should see: "Connected. Spurn accepted your secret key."
Once saved, the secret key field shows blank. Leave it blank to keep the saved key, type a new one to replace it, or tick Remove the saved secret key to delete it.
Visitor IP header#
The plugin sends Spurn the visitor's IP address. Behind a CDN or a load balancer, the address PHP sees is the proxy's, and the real one is in a header.
| Your setup | Choose |
|---|---|
| No proxy in front of WordPress | Direct connection |
| Cloudflare | Cloudflare |
| A proxy that sets X-Real-IP (many nginx setups) | X-Real-IP |
| A load balancer that sets X-Forwarded-For | X-Forwarded-For first address |
Only pick a header your proxy actually sets. Without a proxy, anyone can send these headers and fake their address.
What the plugin does#
The tag. It adds this to <head> on every page, with your public key:
<script async src="https://spurn.io/s.js" data-site="sp_pub_XXXXXXXXXXXXXXXXXXXXXXXX"></script>
The server hit. When a page loads with an ad click id or paid UTM tags, the plugin sends the visitor's IP, user agent, URL, referrer and language to Spurn. The request is non-blocking with a 0.5 second timeout, and PHP never waits for the answer. Organic visits send nothing.
Order conversions. At checkout, classic or block, the plugin copies the Spurn cookie (_spc) onto the order. When WooCommerce marks the order paid (woocommerce_payment_complete), the plugin reports the order number, total and currency to Spurn. If a payment method never fires that hook, the thank-you page sends it instead, for paid and on-hold orders. Each order is reported once; the plugin records that on the order. Only orders from shoppers who arrived on a paid click carry the cookie and get matched.
To switch the tag off, for example because you load it another way, return false from the spurn_print_tag filter.
Check it works#
- Add your own IP address to the allowlist in Spurn (Blocking, then Allowlist), so your tests are never blocked.
- Open your store with a test click id:
https://yourstore.com/?gclid=test-123. - Open Clicks in Spurn. The visit appears within a minute. The site's Install tab shows Receiving and the time of the last server hit.
A test landing counts as a real paid click and uses one credit.
Troubleshooting#
Test connection fails. Check you pasted the secret key, not the public one, that the key hasn't been revoked, and that Spurn address is https://spurn.io. Your host must allow outgoing HTTPS requests to spurn.io.
The tag runs but no server hits arrive. A full-page cache served the ad landing without running PHP, so the plugin never saw it. The tag still works. Exclude URLs with gclid, msclkid or fbclid in the query string from the cache (many caches already skip them). The tracking template (/docs/guides/tracking-template) also records the IP behind Google and Microsoft clicks.
Every click shows the same IP. That's your proxy's address. Set the visitor IP header.
Clicks are rejected for the wrong site. Spurn checks that the page reporting a click belongs to your site's domain or one of its extra hosts. Add any other domain your store answers on in Sites, then your site.
The tag is blocked. If your site sends a Content Security Policy, allow script-src https://spurn.io and connect-src https://spurn.io. Ad blockers can stop the tag in your own browser; the server hit still records the click.
A consent banner holds the tag back. If your consent tool blocks scripts until the visitor accepts, the tag waits too. The server hit doesn't depend on it.
Orders don't show as conversions. Orders are only matched for shoppers who arrived on a paid click. Orders created by hand in the admin have no Spurn cookie and aren't reported.
Removing the plugin#
Deactivate and delete it under Plugins. Deleting it removes its settings from your database.
What data is sent#
- From the tag, on paid landings only: the landing URL and referrer, browser signals used to spot automation, and engagement such as time on page. See /docs/detection.
- From the server hit, on paid landings only: URL, IP address, user agent, referrer and language.
- From orders: order number, total, currency, and the Spurn page view and click ids from the cookie. No names, emails or addresses.