=== Praised AI Crawler Logs ===
Contributors: praised
Tags: ai, seo, geo, analytics, crawlers
Requires at least: 5.6
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See which AI crawlers fetch your pages — GPTBot, ClaudeBot, PerplexityBot and the rest. Visitor traffic never leaves your server.

== Description ==

Before an AI assistant can cite your site, something has to fetch it. This plugin
records which AI crawlers actually do, and reports them to your Praised
workspace so you can see what is being read, how often, and which pages.

It distinguishes three kinds of crawler, because they mean different things:

* **Training** — corpus collection (GPTBot, ClaudeBot, CCBot). Long-term.
* **Search** — building an answer engine's index (OAI-SearchBot, PerplexityBot).
* **Live** — a fetch triggered while an assistant is answering someone's question
  right now (ChatGPT-User, Perplexity-User). The strongest signal that your page
  is being surfaced in real answers.

**Your visitors are not tracked.** A request is checked against a list of known AI
crawler user-agents before anything is recorded. Requests from people are never
stored, never queued, and never sent anywhere. There is no cookie, no script added
to your pages, and no change to what your visitors receive.

= What is sent =

For AI crawler requests only, and only when you have entered an API key:

* the crawler's User-Agent string
* the path requested (no query string)
* your site's hostname
* the HTTP status your site returned
* the time of the request
* the address the request came from

The address is used to verify the crawler was genuine — a User-Agent is a string
anyone can type, so it is checked against the vendors' published IP ranges. It is
used for that check and then discarded: Praised stores no address column, and
a test fails their build if one is ever added.

Hits are queued in your database and sent in batches every five minutes, so the
plugin adds nothing to your visitors' page load.

= External service =

This plugin sends data to the Praised API at `https://api.praised.co`,
which requires a Praised account and an API key that you provide. Nothing is
sent until you enter one.

* Terms: https://praised.co/terms
* Privacy: https://praised.co/privacy

== Installation ==

1. Install and activate the plugin.
2. In your Praised workspace, go to Settings → API keys and create a key.
3. In WordPress, go to Settings → Praised and paste the key.
4. Click **Test connection**. A test hit is recorded in your workspace so you can
   confirm it works without waiting days for a real crawl.

If your site is behind Cloudflare or your own reverse proxy, set **Visitor address
from** to match. The settings screen shows which address it currently resolves to,
so you can check it against your own.

== Frequently Asked Questions ==

= Does this slow my site down? =

No. The check runs after your visitor has already been served, and only writes a
row when an AI crawler is detected. Sending happens on a background schedule.

= Does it track my visitors? =

No. A request has to match a known AI crawler's user-agent before anything at all
is recorded. Human traffic is not stored or transmitted.

= Why do my hits say "can't verify"? =

Because the address the request arrived from could not be checked. Usually that
means the **Visitor address from** setting does not match your hosting setup, or
the crawler's vendor publishes nothing to check against (Anthropic's ClaudeBot
runs on shared cloud addresses). "Can't verify" is not the same as "fake" — it
means the check could not run.

= What happens if Praised is unreachable? =

The queue is kept and retried on the next run. Nothing is discarded on a failed
send. If the API is unreachable for a very long time the oldest queued hits are
eventually dropped so the queue cannot fill your database, and the settings screen
tells you how many.

= Can I remove it cleanly? =

Yes. Deleting the plugin drops its table and removes its options. Deactivating
leaves the queue intact, so you can deactivate temporarily without losing data.

== Changelog ==

= 1.1.0 =
* The API origin can now be changed without reinstalling. It is a setting on
  the plugin screen, and the API can hand out a new one, which the plugin
  adopts on its next successful send. Before this the origin was fixed at build
  time, so a change of address meant every install had to be updated by hand.
* The screen now shows where this site is actually sending, and says so if that
  address was updated automatically.

= 1.0.0 =
* First release.
