=== Crawler Record ===
Contributors: dizzysoft
Tags: googlebot, bingbot, gptbot, seo, robots
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Crawler Record tells you the last time each of the most common search/LLM chatbots visited (Google, ChatGPT, etc) and the pages at which they looked. 

== Description ==

**Crawler Record** shows when Google, ChatGPT, Claude, and other top bots last visited pages on your website, so you can be confident your pages are being crawled. This is the first step in ensuring these platforms index your website so they can serve it to visitors. The data covers several top user-agents, including:

- Google
- Bing
- ChatGPT (OpenAI)
- Claude (Anthropic)
- Perplexity
- Meta
- Apple
- Amazon
- DuckDuckGo
- Common Crawl

Administrators with `manage_options` can view this information:

- **Admin page**: a grouped list of all crawlers, with last seen time, last page, and robots.txt status for the crawler.  
- **Recent Pages**: From the admin page, you can select a crawler and see its latest visited pages, the response status WordPress observed, and a destination when WordPress exposes one for a retained 3xx response.
- **Crawler Activity Overview**: Review 28-day visit totals, response-code health, crawler mix, a daily activity timeline, and crawler staleness. URL reports use up to the 50 most recent recorded visits per crawler.
- **Crawler Status Overview**: Filter the main dashboard and crawler table by crawlers that visited within 28 days, have become stale, or have never visited. The unfiltered dashboard includes the stale-crawler age distribution alongside current activity; the Stale view focuses on that distribution, latest-visit details, and Recent Pages links instead of empty or potentially misleading historical metrics.
- **Header Codes for User-Agents**: Did a user-agent successfully visit a page (2xx), receive a 3xx response, or land on a page that was missing or inaccessible (4xx)? Crawler Record will show you. The 3xx report includes every retained 3xx status, including 304 Not Modified; only responses with an observable redirect destination show where the request was sent.
- **Admin Bar (front-end)**: quick-glance status for all user-agent visits.
- **Per Page/Post**: From the edit screen on any page or post, you can see the last time each crawler visited that page. Administrators can also open the main dashboard or an individual crawler's Recent Pages report from this box.

**Robots-aware:** The plugin checks your **robots.txt** and evaluates Allow/Disallow rules for a given path. WordPress's “Discourage search engines” preference is reported separately because it asks compliant search engines to avoid indexing.

**Response-aware:** Recent visits include the final HTTP status WordPress can observe, including ordinary WordPress 404 pages and 3xx responses that occur after tracking begins. The 3xx report groups all retained 3xx statuses together; 304 Not Modified does not redirect and therefore has no destination. Other 3xx rows show a destination only when WordPress/PHP exposes one. Responses served by a CDN, web server, static cache, or security layer before WordPress runs cannot be recorded.

**Identification note:** Crawler identification is based on the supplied user-agent string. User-agent strings can be spoofed, and this plugin does not verify IPs.

Learn [**how to use this plugin**](https://www.dizzysoft.com/crawler-record-plugin-for-wordpress/).

= Highlights =
* Supports common user-agent variants for Google, Bing, OpenAI (ChatGPT), Anthropic (Claude), Perplexity, Meta, Apple, Amazon, DuckDuckGo, and Common Crawl.
* robots.txt status computed from a local physical or WordPress virtual source without outbound requests.

= Known limitations =
* Can only track crawlers from the time the plugin is installed—it cannot reconstruct earlier visits.
* Per-post “last seen” timestamp and user-agent metadata update at most once every 10 minutes by default. Separately, rapid same-crawler, same-URL, same-status visits are suppressed for 30 seconds, and a high emergency ceiling retains up to 50 visits per crawler per minute. 
* Concurrent requests matching the same crawler are not coordinated. One database write may replace another, causing a visit to be absent from recent history or daily totals, or causing the latest-visit fields to reflect whichever write finished last. Dashboard totals are therefore approximate retained activity rather than an exact raw access log because of throttling, retention limits, and possible concurrent writes.
* Response codes are available only for requests that reach WordPress. Responses served earlier by a CDN, web server, static cache, or security layer are outside the plugin's visibility.
* The 3xx report includes all retained 3xx statuses, including 304 Not Modified. Redirect destinations are available only when WordPress/PHP exposes a Location header. Redirects issued before WordPress runs cannot be recorded, and a followed destination is retained as a separate visit if it reaches WordPress.
* Stored source and redirect URLs include scheme, validated host, optional port, and path. Query strings are omitted to avoid retaining sensitive tokens, personal data, and high-cardinality tracking parameters. Reverse-proxy configuration can affect the scheme WordPress observes.
* URLs up to 114 characters are stored normally. URLs from 115 through 1,028 characters retain the visit with a 100-character prefix and an excessive-length marker; they are displayed with an ellipsis and are not linked. URLs longer than 1,028 characters are omitted from URL-level reports. Sitewide tracking for such requests is subject to the 30-second suppression window, while applicable per-post metadata uses its separate 10-minute throttle.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install via the admin Plugins screen.
2. Activate the plugin.
3. Visit **Crawler Record** under **Admin → Crawler Record** to review crawler activity.

== Frequently Asked Questions ==

= Why are there no crawler visits recorded? =
This plugin can only begin tracking crawler/bot visits from the time you install it—not before. It may take several days or weeks, depending on your website's popularity, before a crawler visits.

= Why do I see the indexing warning? =
If **Settings → Reading → Discourage search engines** is enabled, the plugin explains that WordPress asks compliant search engines not to index the site. This does not prevent access, so robots.txt status is evaluated separately.

= Why doesn't this data align with my website visitors? =
You're comparing two different things: user-agents and human visitors. This plugin measures requests from crawler user-agents, not visits from people.

= How can I get a user-agent to visit my website? =
Several factors contribute, including your website's authority, popularity, internal linking, and links from other trusted websites. A crawler visit does not guarantee that a platform will add the page to its index.

== Screenshots ==

1. Dashboard for Crawler Record shows when the last crawler visited and how it interacted with your website.
2. Crawler Record Dashboard includes a crawler activity overview, including HTTP response codes and crawl activity.
3. Delve into successful visits (2xx HTTP response codes) of crawlers.
4. The dashboard lists common crawlers from platforms such as Google, Bing, ChatGPT/OpenAI, Claude/Anthropic, and many more.

== Changelog ==
= 1.0.0 =

* Added a 28-day activity overview showing crawler trends, crawler mix, response-code health, and crawlers that are recently active, stale, or not yet seen.
* Added focused reports for successful requests, redirects, and missing or inaccessible pages, with frequently requested URLs and recent visit details.
* Added individual crawler dashboards with recent pages, response statuses, redirect destinations, plain-language descriptions, and links to official documentation.
* Added Amazonbot, Amzn-SearchBot, Amzn-User, and improved recognition of crawler variants from other platforms.
* Improved robots.txt reporting with clearer crawler-specific results and a separate explanation of WordPress’s search-engine visibility setting.
* Improved dashboard clarity, accessibility, keyboard navigation, chart readability, mobile layouts, the post editor summary, and the front-end admin bar.
* Confirmed compatibility with WordPress 7.1.

= 0.9.4 =
* Confirmed compatibility with WP 7.0+
* Improved crawler detection accuracy and reduced false matches- especially with Bing.
* Made version matching more resilient to future changes.
* Added support for the Common Crawl (CCBot): https://commoncrawl.org/ccbot
* Improved handling of user-triggered agents and `robots.txt` behavior.
* Improved labels and administrative reporting.
* Added crawler-specific fallback behavior where required.
* Removed irrelevant history links for non-crawling control tokens.
* Removed reference to Microsoft Copilot, since it uses Bingbot.

= 0.9.3 =
* Minor changes and updates.

= 0.9.2 =
* Added Recent Pages history for each crawler.
* Added support for additional crawler variants including Google-Agent (mobile and desktop), Google-Extended, Bing (Search, Chat, and Copilot), Claude-SearchBot, Perplexity-User, DuckDuckGo AI, Applebot-Extended, and Meta-ExternalFetcher.
* Improved crawler tracking for non-post frontend URLs such as archives, taxonomy pages, and other site URLs.
* Improved site-wide reporting so the latest page visited by each crawler is more accurate.
* Improved admin bar reporting for both singular content and non-singular frontend URLs.
* Improved robots.txt reporting with clearer diagnostics showing the matched group and rule.
* Added informational robots status handling for agents that may ignore or bypass robots.txt, such as Google-Agent and Meta-ExternalFetcher.
* Improved handling of the WordPress “Discourage search engines” setting with clearer blocked-status warnings in the admin interface.
* Improved storage of recent crawler activity with bounded recent-page history per agent.

= 0.9.1 =
* Fixed error on any WP archive pages (pages that list posts).

= 0.9.0 =
* Updated for WordPress 6.9
* Now monitoring for Meta and Apple User-Agents
* More accurate site-wide UA reporting.
* Ensured video tutorial appears on all admin screens.
* Fixed small code errors.

= 0.8.0 =
* Google updated its user-agents, so I updated the matching strings to account for these changes.

= 0.7.0 =
* The robots.txt checker wasn't actually working. It does now.
* When you look at the report in the admin section, the robots checker is looking for a site-wide rule; when you look at the back-end of a page, the robots checker is looking at that particular page.
* If a page is blocked by the robots.txt file, a link appears sending you to the robots.txt file.
* Added a video to explain how to use this plugin.

= 0.6.0 =
* Clarified distinction between Google bots.
* Better distinguishes Bingbots.
* Cosmetic changes to page in admin section.
* Clearer documentation.

= 0.5.0 =
* First public release

== Privacy ==
This plugin stores:
- **Timestamps** of crawler visits (float, with microseconds)
- **Exact matched crawler user-agent strings**, bounded to 512 characters
- **Last URL** and a bounded 50-visit recent history per crawler
- **Final HTTP response status** observable by WordPress for recent crawler visits
- **Observable redirect destination**, when PHP exposes one for a retained 3xx response other than 304 Not Modified
- **Last post ID** per crawler (for admin performance)

Stored source and redirect URLs omit query strings. Incoming hosts are validated and used only for reporting; they are never used for redirects, filesystem access, or outbound requests. Existing URL length limits apply independently to redirect sources and destinations.

The plugin stores requests matching configured crawler patterns, but user-agent strings can be spoofed. It performs no IP verification and transmits no data to third parties.

Crawler reports, the front-end admin-bar menu, and the post/page meta box require `manage_options`. Source URLs with hosts outside the configured WordPress home/site hosts are displayed as non-clickable diagnostic text. Uninstall removes all current and legacy Crawler Record options, transients, and post metadata from each site in a multisite network; WordPress removes the plugin files themselves.

== License ==
GPLv2 or later. See LICENSE file.
