=== Spurn ===
Contributors: spurn
Tags: click fraud, google ads, woocommerce, ad fraud, bot protection
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Checks every paid click to your site and keeps the bots and click farms behind fake ones out of your Google, Microsoft and Meta ads.

== Description ==

Spurn stops paying for clicks that never shop. It checks every paid-ad click to your WordPress or WooCommerce site, finds the bots, click farms, competitors and accidental taps behind the fake ones, and keeps them away from your ads.

This plugin connects your site to your Spurn account. It does three things:

* **Adds the Spurn tag to every page.** One small script, loaded asynchronously. It only does anything on visits from a paid ad (a click id such as gclid or msclkid, or paid UTM tags). Organic visits are ignored and never counted.
* **Checks paid clicks from the server.** When a visitor lands from an ad, the plugin tells Spurn the visitor's IP address and browser from your server, so Spurn sees the click even when the visitor's browser never runs JavaScript. The request is sent in the background with a half-second cap: your pages are never slowed down.
* **Reports WooCommerce orders.** Each paid order is sent to Spurn once, matched to the ad click that brought the shopper, so you can see which clicks turned into sales and which never would.

What you get in Spurn:

* A verdict for every paid click, with its reasons: data centre traffic, VPNs and Tor, repeat clicks from one address or device, automation, visits from outside the countries you target.
* Automatic IP exclusions in Google Ads, including Performance Max through the account-level list.
* Exclusion audiences in Microsoft Ads and Meta Ads.
* Evidence packs for refund claims on clicks you already paid for.

Spurn is priced on paid clicks only. A free plan covers 1,000 paid clicks a month on one site.

== Installation ==

1. Install and activate the plugin.
2. In Spurn, open Sites, choose your site (or add it with the WordPress or WooCommerce platform), then open Keys.
3. In WordPress, go to Settings > Spurn. Paste the public key (starts with sp_pub_) and the secret key (starts with sp_sec_). Save changes.
4. Press Test connection. You should see "Connected. Spurn accepted your secret key."
5. If your site sits behind Cloudflare or another proxy that sets the visitor's address in a header, choose that header under Visitor IP header. Otherwise leave it on Direct connection.

The first paid click shows in your Spurn dashboard within a minute of arriving.

== Frequently Asked Questions ==

= Does the plugin slow my site down? =

No. The tag loads asynchronously, and the server check is sent without waiting for an answer, capped at half a second. Visits without ad parameters are not touched at all.

= Do I need WooCommerce? =

No. On a plain WordPress site the plugin adds the tag and the server check. With WooCommerce it also reports orders.

= My site uses a page cache. Does it still work? =

The tag works on cached pages. The server check runs only when WordPress builds the page, so a cache that serves ad landings without running PHP skips it for those visits. Many caching plugins can exclude URLs with gclid, msclkid or fbclid; doing so gives Spurn the server view of every paid click.

= Which payment methods are covered? =

All of them. Orders are reported when WooCommerce marks them paid. For bank transfer, cash on delivery and similar methods, they are reported when the shopper reaches the order received page with the order on hold or paid. Each order is sent once.

= Is the secret key safe? =

It is stored in your WordPress database, is never printed back into the settings screen, and is only sent to Spurn. Never put it in a page or a theme.

== External services ==

This plugin connects to Spurn (https://spurn.io), a click-fraud protection service, and needs a Spurn account. It sends data to Spurn in these cases:

* On every page view, the visitor's browser loads the Spurn tag from https://spurn.io/s.js. On visits from a paid ad, the tag sends the landing URL, referrer, browser and device signals and engagement (time on page, scrolling) to Spurn.
* On visits from a paid ad, your server sends the landing URL, the visitor's IP address, user agent, referrer and browser language to https://spurn.io/api/v1/hit.
* When a WooCommerce order is paid, your server sends the order number, order total, currency and the ad click id from the shopper's Spurn cookie to https://spurn.io/api/v1/conversion. No names, email addresses, postal addresses or items are sent.
* When you press Test connection, your server sends one test request to https://spurn.io/api/v1/hit.

Spurn uses this data to decide whether each paid click is genuine and to keep fake ones away from your ads. Terms of service: https://spurn.io/legal/terms. Privacy policy: https://spurn.io/legal/privacy.

== Privacy ==

The Spurn tag sets a first-party cookie, _spc, which holds a random page view id and the ad click id, for 30 days, and keeps a random visitor id in the browser's local storage. Both exist only for visitors who arrived from a paid ad. Add them to your cookie policy. Spurn processes this data on your behalf; see the data processing agreement at https://spurn.io/legal/dpa.

== Changelog ==

= 1.0.0 =
* First release: the Spurn tag, server checks of paid landings, WooCommerce order reporting, and a connection test.

== Upgrade Notice ==

= 1.0.0 =
First release.
