=== Aiso AI Crawler Analytics ===
Contributors: bentannenbaum
Tags: ai, analytics, crawler, bot, seo
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See which AI assistants — ChatGPT, Claude, Perplexity, Google and more — crawl your site, broken down by assistant, crawler, purpose and page.

== Description ==

Search is moving inside AI assistants. When someone asks ChatGPT, Claude, Perplexity or Google's AI a question, those assistants quietly fetch real web pages — and **those fetches are the new impressions**. Most analytics tools never show them, because AI crawlers don't run JavaScript and don't appear in client-side analytics.

**Aiso AI Crawler Analytics reads the requests that actually hit your server** and turns them into a clean, agency-ready dashboard right inside wp-admin. Think of it as the "AI visibility" companion to your security log — focused entirely on AI search performance instead of threats.

= What you get =

* **Headline KPIs** — total AI-crawler hits, "chat impressions" (live fetches during AI answers), distinct crawlers, and pages crawled.
* **By AI platform** — ChatGPT (OpenAI), Claude (Anthropic), Perplexity, Google/Gemini, Microsoft Copilot, Meta AI and more.
* **By crawler / user-agent** — the exact bots (GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, Claude-User, PerplexityBot, Googlebot, Bingbot, Bytespider, Applebot…).
* **By purpose** — training vs. citation-indexing vs. **live chat impressions** vs. search vs. agentic browsing, so you know whether a bot is just training a model or actively quoting you in an answer.
* **By page** — which URLs AI assistants read most, with per-page impression counts.
* **Over time** — a daily activity chart so you can see trends and spikes.
* **Live hit log** — recent crawler visits with country and a source-IP verification badge that flags possible spoofed user-agents.
* **CSV export** — hand clients a report in one click.

= Built for agencies =

Connect the plugin to a free Aiso account and every site you manage reports into one central place, so your AI-visibility data is kept long-term and viewable across your whole portfolio. Not an agency? The plugin works completely on its own — install it and the dashboard fills up locally with **nothing sent anywhere**.

= Privacy-first =

Visitor IPs are anonymised by default (stored only as a salted hash). The plugin records AI-crawler requests, not your human visitors, and never transmits any data externally until you explicitly connect an Aiso account.

== Installation ==

1. Upload the `aiso-ai-crawler-analytics` folder to `/wp-content/plugins/`, or install it from **Plugins → Add New** in your dashboard.
2. Activate the plugin through the **Plugins** screen.
3. Open **AI Crawlers** in the admin menu to see your dashboard. It starts filling up as AI crawlers visit your site.
4. (Optional) Go to **AI Crawlers → Settings** and click **Connect** to link a free Aiso account so your data is stored long-term and aggregated across all your sites.

To test it immediately, request your home page with a crawler user-agent:

`curl -A "Mozilla/5.0 (compatible; GPTBot/1.1; +https://openai.com/gptbot)" https://yourdomain.com/`

Reload the dashboard after a few seconds and the hit appears.

== Frequently Asked Questions ==

= Do I need an account to use this? =
No. The dashboard works fully on its own using a local table — nothing is sent anywhere. An Aiso account is optional and only adds long-term, cross-site storage.

= What are "chat impressions"? =
Some crawlers (ChatGPT-User, Claude-User, Perplexity-User, DuckAssistBot…) fetch a page **the moment an AI assistant is answering a user**. That live fetch is the closest equivalent to an impression inside the chat, so we surface it as its own metric.

= Will this slow down my site? =
No. Non-AI traffic does zero database work. For the small fraction of requests that are AI crawlers, a single row is written on shutdown, and any upload to Aiso happens after the response has already been sent to the visitor (via fastcgi_finish_request where available).

= How accurate is detection? =
Detection is user-agent based, matching the Aiso AI-bot directory. Where a provider publishes official IP ranges (OpenAI, Microsoft, Perplexity, Amazon, Meta, Common Crawl, Huawei, Parallel.ai), the plugin also checks the source IP and flags mismatches as possible spoofs.

= Does it work behind Cloudflare or a CDN? =
Yes. It reads common edge headers (CF-Connecting-IP, CF-IPCountry, etc.) to recover the real client IP and country.

= How is this different from a security plugin like Wordfence or Cerber? =
Those focus on threats. This focuses on AI-search visibility: who from the AI world is reading your content, what they read, and when — framed as marketing impressions, not security events.

== Screenshots ==

1. The AI Crawler Analytics dashboard: KPIs, platform and purpose breakdowns.
2. Per-page breakdown and daily activity over time.
3. Live crawler hit log with source-IP verification badges.
4. Settings: connect an Aiso account, privacy and retention options.

== External services ==

This plugin connects to the Aiso API (https://www.getaiso.com) **only when you enable syncing by connecting an account**. It is used to (a) optionally generate an API key for your site and (b) store your AI-crawler hits centrally so they are retained long-term and can be viewed across multiple sites.

* **When data is sent:** only while "Send data to Aiso" is enabled in Settings, and only for AI-crawler hits (not human visitors).
* **What is sent:** the requested path and URL, the crawler's user-agent, the detected bot and company, an optionally-hashed source IP, a two-letter country code, the HTTP status, a timestamp, your site URL, and your Aiso API key.
* **What is not sent:** human-visitor analytics, post content, or personal data of your readers.

By connecting an account you agree to Aiso's terms and privacy policy:

* Terms: https://www.getaiso.com/quick_links/terms_of_service
* Privacy policy: https://www.getaiso.com/quick_links/privacy_policy

If you never connect an account, the plugin makes no external requests and stores all data locally on your own server.

== Changelog ==

= 1.0.0 =
* Initial release: local AI-crawler dashboard (platform, crawler, purpose, page, over-time breakdowns), source-IP verification, CSV export, and optional sync to a central Aiso account.

== Upgrade Notice ==

= 1.0.0 =
First release.
