Skip to content

About

Click-fraud protection for Google/Microsoft/Meta Ads: detects invalid clicks, excludes bad IPs upstream, compliant split-URL A/B testing with audience-based routing. No cloaking.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

ClickGuard

A learning project that protects Google Ads, Microsoft Ads and Meta Ads campaigns from competitors and bots that click your ads to burn your budget.

It detects invalid clicks, excludes offending IPs at the ad platform (so those visitors stop seeing your ads), and produces evidence reports for refund requests. Every visitor, including ad reviewers and crawlers, sees exactly the same website: the tracker only observes and never changes the page.

Screenshots

Dashboard — ad clicks, how many look invalid, estimated wasted spend, and the A/B split.

Dashboard

Live monitor — clicks streaming in with verdict, score, geo/network, A/B variant, query string and reasons.

Live monitor

Sites & streams — one stream per traffic source with quick A/B controls (Auto / All A / All B) and a routing-rules badge.

Campaign streams

Routing rules (Auto) — audience-based rules decide A vs B; the % split is the fallback. Click identifiers can't be used (no cloaking).

Routing rules

How it works

  1. A small script (packages/tracker/tracker.js) on your landing page reports visits that arrive from an ad (gclid, gbraid, wbraid, msclkid, fbclid, or an ad utm_source), plus basic browser signals and, when the page is closed, engagement (time on page, scroll, pointer and key activity).

  2. The server enriches each click with country and network (MaxMind GeoLite2) and scores it 0–100 with independent rules (apps/server/src/scoring/rules.ts):

    Rule Points
    Same IP clicks the same campaign more than N times in a window 40–60
    Same device fingerprint on the same network repeats 30
    Click ID reused / ad UTM without a click ID 50 / 15
    Country outside the campaign's targets 35
    Hosting, cloud or VPN network 40
    Automation (navigator.webdriver, empty browser properties) 15–60
    Instant bounce / no interaction / no engagement beacon 25 / 15 / 10
    Burst from one /24 subnet or one network 30 / 20
    User agent claims to be AdsBot/bingbot but fails DNS verification 70

    Verified Google, Microsoft and Meta crawlers are tagged crawler and never scored or excluded. Visits carrying a valid cg_test key are tagged test and likewise skipped (see Test traffic below).

  3. Clicks at or over a stream's exclude threshold add the IP to that stream's exclusion list, with an expiry (residential IPs get reassigned).

  4. Exclusions reach the platforms in one of two ways:

    • Google Ads: synced automatically every 5 minutes through the Google Ads API (negative CampaignCriterion with IpBlockInfo, limit 500 per campaign; the highest scores win).
    • Microsoft Ads: download the IP list and paste it into the campaign's IP exclusions.
    • Meta Ads: has no IP exclusions. Use the evidence CSV to report invalid activity.

Run it

Requires Node 23.6+ (it runs TypeScript directly and uses the built-in node:sqlite).

git clone https://github.com/allimist/clickguard.git
cd clickguard
npm install
cp .env.example .env          # set APP_SECRET and ADMIN_PASSWORD
npm run dev                   # API :3000, admin :5173, demo sites :5174 (A) and :5175 (B)
  1. Open http://localhost:5173 and sign in as admin.
  2. Under Sites & streams, create a site with domain localhost and a stream with utm_campaign brand.
  3. Put the site key in .env as DEMO_SITE_KEY, restart, and open http://localhost:5174/?gclid=test&utm_campaign=brand. The visit shows up on the Live page.

A/B landing test (split-URL)

A stream can run an A/B test between two landing sites. The ad always points at site A (apps/demo/site-a.html, served on :5174, the one with the tracker). In the stream settings, turn on Run an A/B landing test, set the split, and point Variant B URL at site B (apps/demo/site-b.html, served on :5175).

Each visitor is assigned A or B by a random per-visitor id (cg_vid in their browser), so the same visitor always sees the same variant. Visitors assigned to B are redirected from A to the B URL with the ad parameters carried over; everyone else stays on A. The assignment depends only on the visitor and the campaign — never on location, network, referrer or fraud score — so reviewers and customers are bucketed identically. This is a standard split-URL test, not cloaking: both pages are real, and nobody is shown a different page based on who they appear to be.

Because B visitors leave page A immediately, their page-A engagement is not measured and engagement rules are skipped for them. Site B is a separate site without the tracker, so a redirect never records a second click. Per-variant clicks, clean rate and average time on page appear on the Dashboard.

Quick A/B controls: in the streams table each stream has Auto / All A / All B buttons that set the fallback for visitors who match no routing rule — Auto is a balanced split, All A keeps them on A, All B redirects them to B. The same three buttons next to Add stream apply to every stream on the site at once. A site can hold one stream per platform (e.g. a Google, a Microsoft and a Meta stream, each matched by its own utm_campaign), and all of them can run the same A/B test against sites A and B.

Routing rules (who goes to A vs B)

Beyond the percentage split, a stream can carry an ordered list of routing rules. Each rule is if <attribute> <operator> <value> → send to A or B; rules are evaluated top to bottom, the first match wins, and anything matching no rule uses the fallback split. So you can set the fallback to All B (100%) and still add a rule like country is GB → A — everyone goes to B except GB visitors. Rules keep working at every fallback setting.

  • Attributes: country, device (mobile/tablet/desktop), language, or a query-param value.
  • Operators: is, is not, is one of, greater than, less than (numeric).
  • Rules route only on attributes that treat an ad reviewer the same as a real customer. Routing on a click identifier (gclid, gbraid, wbraid, msclkid, fbclid) or by the length/validity of one is rejected — that would be cloaking (showing reviewers a different page than real clicks), which this project does not do.

Test traffic (skip fraud checks)

Each site has a secret test key (shown on its page in the admin panel). Append &cg_test=<key> to any landing URL and that visit is recorded as test: scored 0, never flagged, never auto-excluded, and kept out of the fraud stats — so your own testing doesn't look like fraud. Each test visit is treated as a brand-new visitor, so the A/B assignment isn't remembered between tries and you can re-check routing rules freely. Regenerate the key if it leaks. 4. Generate realistic mixed traffic (normal users, a repeat clicker, a VPN click farm, headless bots, out-of-geo visitors, a replayed click ID, a fake crawler):

npm run simulate -- --site <SITE_KEY> --geo US

For country and network data, download the free GeoLite2 Country and ASN databases from MaxMind into data/. Without them, the geo and datacenter rules stay inactive.

For production: npm run build, then NODE_ENV=production npm start -w apps/server serves the API, the tracker and the built admin UI from one port. Put it behind HTTPS and set TRUST_PROXY=true behind a reverse proxy.

Tests

npm test         # scoring rules, crawler verification, API, tracking pipeline, Google sync (mocked)
npm run typecheck

Layout

apps/server     Fastify API, tracker endpoints, scoring, exclusion sync (SQLite)
apps/admin      React admin panel: dashboard, live monitor, clicks, exclusions, reports, sites & streams
apps/demo       Two local landing sites: site A (:5174, ad landing) and site B (:5175, A/B variant)
packages/tracker  The embeddable tracker script
packages/shared   Types shared by server and admin
scripts/simulate.ts  Traffic simulator (dev mode only)

Scope — not a cloaker

This tool protects ad spend by detecting invalid clicks and excluding bad IPs upstream at the ad platform. Every visitor — reviewers, crawlers, real customers — is served the same site, and A/B routing never keys on signals that tell a reviewer apart from a customer. It deliberately does not do cloaking (white-page/black-page switching, routing by click-ID validity, etc.), because that violates Google/Microsoft/Meta policy and gets ad accounts banned.

Limitations

  • The device fingerprint is deliberately coarse, so the repeat-device rule only counts within one network.
  • The datacenter list (apps/server/src/lib/datacenter.ts) is a short curated list of ASNs, not a commercial IP-reputation feed.
  • Microsoft Ads exclusions are export-only; the Bulk/Campaign Management API sync is not implemented.
  • Dev mode honours X-Debug-IP, X-Debug-Country and X-Debug-ASN headers on tracker endpoints so the simulator can fake traffic. They are ignored when NODE_ENV=production.

About

Click-fraud protection for Google/Microsoft/Meta Ads: detects invalid clicks, excludes bad IPs upstream, compliant split-URL A/B testing with audience-based routing. No cloaking.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages