=== RealTrace AI – Real Human and AI Traffic Counter ===
Contributors: adnanlimdi
Donate link: https://profiles.wordpress.org/adnanlimdi/
Tags: traffic counter, visitor analytics, visit counter , Real human tracker, real time traffic
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.1
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Tracks visits via dual-layer detection, classifies human vs AI crawlers, and delivers high-precision offline geolocation analytics.

== Description ==

**RealTrace AI** provides real-time, privacy-first analytics for WordPress. It tracks incoming visitors through a dual-layer approach (server-side capture and client-side non-blocking REST beacons) to distinguish real humans from AI crawlers, search engine indexers, and automated scraping tools.

Unlike standard visitor counters that treat every automated HTTP hit as a genuine person, RealTrace AI filters and segments incoming traffic into three distinct tiers: **Humans**, **AI & LLM Crawlers**, and **Search Engine Bots**.

---

### Bots & Crawlers Detected Out-of-the-Box

RealTrace AI evaluates request patterns, URI endpoints, and User-Agent headers against extensive internal signatures:

#### 1. AI & LLM Crawlers
* **OpenAI:** GPTBot, ChatGPT-User, OAI-SearchBot
* **Anthropic:** ClaudeBot, Claude-Web, Anthropic-AI
* **Google AI:** Google-Extended, Gemini, Gemini Deep Research
* **Perplexity:** PerplexityBot, Perplexity-AI
* **Meta:** Meta-ExternalAgent, Meta-ExternalFetcher, FacebookExternalHit
* **xAI:** GrokBot, xAI-Crawler
* **ByteDance:** ByteSpider
* **DeepSeek:** DeepSeek Bot, DeepSeek Web Crawler
* **Apple:** Applebot-Extended (Apple Intelligence)
* **Mistral AI:** MistralAI Crawler
* **Cohere:** Cohere-AI
* **Amazon:** AmazonBot
* **AI Datasets & Aggregators:** Common Crawl (CCBot), Diffbot, You.com (YouBot), DuckAssistBot, Allen AI (AI2Bot), Webz.io / Omgili, ImageSift, Timpi, Katerat, SentientMachine, Pango

#### 2. Search Engine Indexers
* Googlebot, Google Asset Service, Google Inspection Tool
* Bingbot, Applebot, Baidu Spider, YandexBot / Yandex Engine
* DuckDuckBot, Sogou Spider, Exabot, Qwantify, SeznamBot, PetalBot, CocCoc Bot
* Moz DotBot, AhrefsBot, SemrushBot, Majestic MJ12bot

#### 3. Social Previews & Uptime Monitors
* TwitterBot / X, LinkedInBot, WhatsApp Preview, TelegramBot, Slackbot, DiscordBot, Pinterest Bot
* UptimeRobot, Pingdom, Site24x7, StatusCake, Screaming Frog SEO Spider, Seltz Sitemap Fetcher

#### 4. Developer Tools & Headless Scrapers
* Puppeteer, Playwright, Selenium, Headless Chrome, PhantomJS, Cypress
* Python (Requests, urllib, aiohttp), Scrapy Framework
* cURL, Wget, HTTPie, Postman Runtime, Insomnia
* Node.js (Axios, Fetch, Got), Go HTTP, Java HTTP Client, Apache HttpClient, OkHttp, Guzzle PHP, Perl libwww, WinHTTP

#### 5. Automated Endpoint Scrapers
* Flags unauthenticated direct automated scrapes targeting sensitive or automated endpoints like `/wp-json/oembed/`, `/.well-known/`, `/feed`, `/rss`, `/wp-cron.php`, `/xmlrpc.php`, and `/wp-comments-post.php`.

---

### Included Shortcodes

* `[realtrace_smart_counter]` – Displays a complete visitor card showing total humans, bots, and the verified Human Score percentage.
* `[realtrace_traffic_battle]` – Displays an interactive split progress bar comparing human visitors against AI scrapers.
* `[realtrace_human_counter]` – Outputs the raw formatted count of verified human visitors.
* `[realtrace_ai_counter]` – Outputs the raw formatted count of detected bots and AI scrapers.

== Installation ==

1. Upload the `realtrace-traffic-counter` folder to the `/wp-content/plugins/` directory or install it via the WordPress Plugin search.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Ensure the MaxMind reader library is located in `includes/Geo/MaxMind/`.
4. Go to **RealTrace AI > Settings** and click **Download / Update Geo Database** to stream and verify the offline binary database (`.mmdb`).
5. Use the shortcodes in posts, page templates, block editors, or widget areas.

== Frequently Asked Questions ==

= Does RealTrace AI send visitor IP addresses to external lookup APIs? =
No. RealTrace AI resolves countries using an offline MaxMind binary database stored locally in your `wp-content/uploads/realtrace/` folder. Visitor IPs are processed entirely on your server.

= What happens if the Geo database is missing or corrupt? =
RealTrace AI includes built-in verification. If the `.mmdb` file is missing or interrupted during transfer, the plugin falls back to its multi-octet subnet router, purges any broken files, and presents a one-click download button in the admin interface.

= Can I add custom bot signatures? =
Yes. In **RealTrace AI > Settings**, enter custom substrings under **Custom Bot Signatures** (one signature per line). Any User-Agent matching that text will be classified as an AI bot.

= Does tracking slow down page requests? =
No. Geolocation queries run against an optimized local binary search tree in microseconds, and a built-in visit debounce window prevents repeat hits from the same IP from inflating database load.

== Screenshots ==

1. RealTrace AI analytics dashboard displaying real-time traffic KPI cards (Total Hits, Human Users, AI Scrapers, Search Engine Bots) alongside the complete visitor logs table.
2. Tracker configuration settings for administrator exclusion, debounce duration, IP scanner provider selection, and custom bot signatures.
3. Adding the [realtrace_smart_counter] shortcode in the WordPress block editor.
4. Frontend traffic battle widget ([realtrace_traffic_battle]) displaying live human vs. AI scraper percentage breakdown with a dual progress bar.
5. Filtered log view displaying detected automated bots and AI crawlers with the filter set to "AI Scrapers Only".
6. Frontend smart counter widget ([realtrace_smart_counter]) rendering the live pulse indicator, Human Score percentage, and split metric cards.

== Changelog ==

= 1.1.0 =
* **Feature:** Added native offline binary geolocation using MaxMind `.mmdb` reader support.
* **Feature:** Added an asynchronous admin REST API endpoint (`realtrace/v1/update-geo-db`) for downloading and verifying the Geo database.
* **Feature:** Added binary integrity validation (`\xab\xcd\xefMaxMind.com`) to detect and purge truncated or incomplete downloads.
* **Feature:** Integrated dashboard warning and error notices when the local database is missing or corrupt.
* **Design:** Complete UI redesign of the Settings screen with a brand-aligned layout, status badges, and single-screen feedback banners.
* **Improvement:** Expanded the offline multi-octet fallback subnet router for Middle East and European IP blocks.

= 1.0.0 =
* Initial public release on WordPress.org.