Skip to content
Browse the docs

Install Spurn on WordPress

The Spurn plugin adds the tag to every page and sends a server hit when a paid click lands. It works on any WordPress site; if you run WooCommerce, follow /docs/install/woocommerce instead, which also reports orders.

Before you start#

  • WordPress 6.0 or later and PHP 7.4 or later.
  • 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_…).
  • The plugin zip, spurn-wordpress.zip, from your site's Install tab in Spurn.

Install the plugin#

  1. Go to Plugins, then Add New Plugin, then Upload Plugin.
  2. Choose spurn-wordpress.zip, click Install Now, then Activate.
  3. Go to Settings, then Spurn (or click Settings under Spurn on the Plugins screen).
  4. Under Site keys, paste the Public key and the Secret key.
  5. Under Advanced, set Visitor IP header: Direct connection without a proxy, Cloudflare behind Cloudflare, X-Real-IP or X-Forwarded-For first address behind a proxy that sets that header. Only pick one your proxy really sets. Leave Spurn address as https://spurn.io.
  6. Click Save changes, then 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, or tick Remove the saved secret key to delete it. To switch the tag off, return false from the spurn_print_tag filter.

The plugin then adds the tag to <head> on every page:

<script async src="https://spurn.io/s.js" data-site="sp_pub_XXXXXXXXXXXXXXXXXXXXXXXX"></script>

On a page load with an ad click id or paid UTM tags, it also sends a server hit: the visitor's IP, user agent, URL, referrer and language. The request is non-blocking with a 0.5 second timeout, so the page never waits for Spurn.

Report leads and sales#

Without WooCommerce there is no order to hook into, so you tell Spurn when a visitor converts. Put this on your thank-you page, after a form submission or a sale. In the block editor, add a Custom HTML block:

<script>
  window.spurn = window.spurn || function () { (window.spurn.q = window.spurn.q || []).push(arguments) }
  spurn('conversion', { value: 49.9, currency: 'USD', orderId: 'lead-1001' })
</script>
  • value is in major units (49.9 for $49.90). Leave it out for a lead with no value.
  • orderId is any id that is unique per conversion, so a reload of the page doesn't count twice.
  • The tag only sends a conversion for a visitor who arrived on a paid click. Everyone else is ignored.

If your form or payment plugin can call a webhook from the server, the server API is more reliable: /docs/install/server-api.

Check it works#

  1. Add your own IP address to the allowlist in Spurn (Blocking, then Allowlist).
  2. Open your site with a test click id: https://yoursite.com/?gclid=test-123.
  3. Open Clicks in Spurn. The visit appears within a minute, and the site's Install tab shows Receiving with 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 it hasn't been revoked, and that Spurn address is https://spurn.io. Your host must allow outgoing HTTPS requests to spurn.io.

No server hits arrive. A full-page cache served the ad landing without running PHP, so the plugin never saw it. The tag keeps working, because it runs in the browser. Exclude URLs with gclid, msclkid or fbclid in the query string from the cache (many caches already skip them).

Every click shows the same IP. That is your proxy's address. Set the visitor IP header.

Clicks are rejected for the wrong site. Spurn checks the reporting page against your site's domain and extra hosts. Add any other domain the site answers on in Sites, then your site.

The tag is blocked. With 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.

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 your conversion snippet: the value, currency and id you put in it.

Deleting the plugin under Plugins removes its settings.