=== RealTrace AI – Real Human and AI Traffic Counter ===
Contributors: adnanlimdi
Donate link: https://profiles.wordpress.org/adnanlimdi/
Tags: traffic counter, visitor analytics, ai detector, bot tracker, real time traffic
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.1
Stable tag: 1.1.2
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 Dashboard with timeline trend line graphs, composition donut split, and country distribution.
2. Unified Tracker Settings screen with live binary integrity status and one-click database management.
3. Frontend Smart Counter and Traffic Battle shortcode components.

== Changelog ==

= 1.1.2 =
* **Database Fix:** Resolved SQLite compatibility error in 7-day trend queries by passing date boundaries directly from PHP, ensuring compatibility with standard MySQL, MariaDB, and SQLite (WordPress Playground).
* **Fix:** Resolved PHP 8+ fatal error during plugin activation by eliminating non-static method calls within static activation routines.
* **Database Schema:** Corrected strict formatting in dbDelta schema definition to guarantee clean creation of the `country_code` column and indexes on fresh installs.
* **Stability:** Added WordPress Playground/WASM detection to prevent sandbox download timeouts and false corrupted database alerts.
* **Accuracy:** Reclassified Slackbot and social media preview crawlers under the Other Bot category instead of Human.

= 1.1.1 =
* **Feature:** Added native CSV and JSON log export with active category filter support.
* **Security & Accuracy:** Patched REST probe loophole—direct automated hits to `/wp-json/` routes are now correctly flagged as automated scrapers instead of human visits.
* **Fix:** Excluded internal tracking endpoints from server-side hit logging to eliminate self-ping loops.

= 1.1.1 =
* **Feature:** Added native CSV and JSON log export with active category filter support.
* **Security & Accuracy:** Patched REST probe loophole—direct automated hits to `/wp-json/` routes are now correctly flagged as automated scrapers instead of human visits.
* **Fix:** Excluded internal tracking endpoints from server-side hit logging to eliminate self-ping loops.

= 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.