=== Trakkr Crawler Tracking ===
Tags: ai, crawlers, analytics, seo, privacy
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.6.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Record requests from known AI crawler user agents and view them in Trakkr. No front-end JavaScript is added.

== Description ==

Trakkr Crawler Tracking records requests whose User-Agent matches a known AI crawler pattern. It runs on the server after WordPress finishes the request, so it can record the final status code without adding a script, pixel, cookie, or public credit to your site.

The plugin is designed for site owners who use the Trakkr service. After you connect WordPress to Trakkr with a WordPress Application Password, Trakkr can retrieve recent crawler records through authenticated REST endpoints and acknowledge the rows it has received.

= What it does =

* Matches known AI crawler and AI assistant User-Agents, including GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, Google-Agent, and others.
* Stores the crawler name, User-Agent, requested URL, request method, referring URL, response status, IP address, country code, and timestamp.
* Removes query strings and fragments from requested and referring URLs before storage.
* Supports common proxy headers from Cloudflare, Sucuri, and other reverse proxies. These IP values are informational and are never used for access control.
* Exposes records only through capability-protected WordPress REST endpoints.
* Adds a dedicated Trakkr Crawler Sync role that can retrieve and acknowledge crawler rows but cannot publish content, edit posts, upload media, change site options, or write files.
* Lets an authenticated site administrator publish approved robots.txt, llms.txt, llms-full.txt, sitemap redirect, structured data, and supported SEO metadata changes from Trakkr.
* Deletes synced local rows after 30 days and unsynced local rows after 90 days.

The plugin does not contact Trakkr or any other external server by itself. It does not load remote code, remote fonts, tracking pixels, or third-party scripts. It does not include a custom updater. WordPress.org supplies plugin updates for the directory release.

== External Service ==

This plugin works with Trakkr, an AI visibility service operated by Trakkr. A Trakkr account is required to view the collected crawler records in the Trakkr dashboard or use Trakkr's connected-site publishing features.

The plugin does not initiate outbound requests. When an authorized user explicitly connects the site in Trakkr, the Trakkr service sends authenticated HTTPS requests to this site's WordPress REST API. WordPress Application Password authentication and WordPress capabilities control access. Crawler-only connections can use a dedicated user with the Trakkr Crawler Sync role. Existing administrator connections remain supported.

For crawler syncing, the response can contain the crawler User-Agent, crawler name and type, requested URL, request method, referring URL, IP address, country code, response status, and timestamp. Query strings and fragments are removed from both URLs. Trakkr uses this data to show crawler activity for the connected site. Trakkr also sends the IDs it received back to WordPress so those local rows can be marked as synced.

If the administrator uses connected-site publishing, Trakkr can read or update only the allow-listed WordPress options, files, post metadata, and publish-operation markers exposed by this plugin. These actions occur only after the administrator connects the site and requests or approves the related action in Trakkr.

* Trakkr service: https://trakkr.ai
* Terms of Service: https://trakkr.ai/terms
* Privacy Policy: https://trakkr.ai/privacy

== Privacy ==

The plugin writes a local database row only when a request's User-Agent matches one of its known AI crawler patterns. User-Agent strings can be imitated, so site owners should still treat the stored IP address and URL paths as potentially personal data.

To reduce collection, query strings and fragments are removed from requested and referring URLs before storage. The plugin does not set cookies and does not add front-end JavaScript.

Synced rows are deleted from the WordPress database after 30 days. Rows that have not been synced are deleted after 90 days. Deleting the plugin removes its database table, scheduled cleanup event, and stored options.

Trakkr keeps connected-site data according to its Privacy Policy. Site owners should review that policy and add the suggested Trakkr text from Settings > Privacy to their own privacy policy where applicable.

== Installation ==

1. In WordPress, go to Plugins > Add New.
2. Search for "Trakkr Crawler Tracking", then install and activate it.
3. In Trakkr, open your site's crawler tracking connection and choose WordPress.
4. For crawler-only access, create a dedicated WordPress user with the Trakkr Crawler Sync role. Use an Administrator only if you also want Trakkr's publishing and site-management features.
5. Create an Application Password for that user and enter it in Trakkr over HTTPS.
6. Confirm the connection in Trakkr. Tracking begins on the next request whose User-Agent matches a known AI crawler pattern.

No WordPress settings screen is required. The crawler feed requires the dedicated `trakkr_read_crawler_visits` and `trakkr_ack_crawler_visits` capabilities. The plugin grants both to its Trakkr Crawler Sync role and to Administrators for backwards compatibility. Site-wide file and option endpoints still require `manage_options`. Post metadata endpoints still verify that the authenticated user can edit the specific post.

== Frequently Asked Questions ==

= Does this slow down my site? =

The matching work is a short in-memory pattern check on each WordPress request. Only a matching request triggers a database insert. Detection runs on WordPress's `shutdown` hook after the response has been generated.

= Does it track human visitors? =

The plugin only records requests whose User-Agent matches a known AI crawler pattern. Regular browser User-Agents are ignored. Because User-Agent strings can be imitated, a matching row is evidence of the claimed crawler identity, not proof that the request came from that company.

= What data is stored in WordPress? =

The `wp_trakkr_crawler_visits` table stores the crawler User-Agent, crawler name and type, requested URL, request method, referring URL, response status, IP address, country code, timestamp, and sync state. Query strings and fragments are removed from both URLs. The `wp_` part follows your site's configured database prefix.

= Does Trakkr need an administrator Application Password? =

No, not for crawler tracking. Use a dedicated account with the Trakkr Crawler Sync role. That role can retrieve crawler rows and mark received rows as synced, but cannot publish content, edit posts, upload media, change site options, or write files. An Administrator or suitably privileged Editor is needed only for the separate connected-site publishing features. Keep each Application Password only in Trakkr and revoke it in WordPress when you disconnect the site.

= Does it work behind Cloudflare or Sucuri? =

Yes, for matching requests that reach WordPress. The plugin can read standard proxy headers to record the reported client IP and country. Requests served entirely from a CDN or blocked before reaching WordPress cannot be recorded by an origin plugin.

= Does crawler tracking work on WordPress VIP? =

The crawler endpoints and database records are compatible with WordPress VIP's read-only application containers. The plugin stores llms.txt content in the WordPress database and serves it through WordPress, so it does not write to the application filesystem. WordPress VIP customers must add the unpacked plugin through their application Git repository and should validate performance in a non-production environment before enabling it in production.

= Does the plugin download or execute remote code? =

No. It contains no remote-code loader and no custom update service. The WordPress.org directory provides updates for this release.

== Screenshots ==

1. The Trakkr setup preview shows the crawler metrics and recent request detail that appear after connection.
2. Trakkr Crawler Tracking is active on WordPress 7.1 with no settings screen or front-end script required.

== Changelog ==

= 1.6.1 =
* Store llms.txt and llms-full.txt content only in prefixed WordPress options and serve it through WordPress.
* Removed all web-root file reads, writes, and deletions.
* Replaced dynamic option API calls with fixed prefixed option names.
* Prefixed the PHP 7.4 list-array compatibility helper.

= 1.6.0 =
* Added the least-privilege Trakkr Crawler Sync role for crawler-only connections.
* Split crawler read and acknowledgement permissions from the broad `manage_options` capability.
* Kept existing Administrator connections working by granting Administrators the new crawler capabilities during upgrade.
* Added multisite-aware activation and uninstall cleanup for the crawler table, role, capabilities, and cleanup schedule.
* Skip optional physical llms.txt writes on read-only application filesystems such as WordPress VIP.

= 1.5.0 =
* Prepared the plugin for WordPress.org directory distribution and WordPress-managed updates.
* Updated compatibility metadata through WordPress 7.1.
* Added complete external-service, privacy, retention, authentication, and uninstall disclosures.
* Removed query strings and fragments before storing requested and referring URLs.
* Replaced Host-header URL construction with the configured WordPress home URL.
* Limited acknowledge requests to 5,000 unique visit IDs.
* Added suggested text to the WordPress privacy-policy guide.
* Migrated physical-file ownership markers from MD5 to SHA-256 while retaining safe upgrade compatibility.
* Added translated REST error messages and explicit text-domain and GPL headers.

= 1.4.2 =
* Content publishing now rejects ambiguous duplicate operation markers instead of choosing one.

= 1.4.1 =
* llms.txt and llms-full.txt can be written as physical files in the web root for hosts that serve text files without reaching WordPress.
* Files are re-created on plugin activation and update. Files not created by this plugin are never overwritten or deleted.

= 1.4.0 =
* Added validated JSON-LD output from Trakkr schema metadata.
* Added llms-full.txt support and an optional same-site sitemap redirect.

= 1.2.0 =
* Moved detection to the `shutdown` hook so recorded status codes are accurate.
* Added request method, referrer, country, proxy IP support, schema migrations, retention, uninstall cleanup, and administrator-only crawler sync.

= 1.1.0 =
* Added authenticated robots.txt and llms.txt management plus publish-operation lookup.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.6.1 =
llms.txt content is now stored in the WordPress database and served virtually. The plugin no longer reads, writes, or deletes files in the web root.

= 1.6.0 =
Crawler tracking can now use a dedicated Trakkr Crawler Sync user without Administrator publishing or site-management access. Existing Administrator connections continue to work.

= 1.5.0 =
This release improves privacy, security, disclosure, and WordPress.org update compatibility without changing the authenticated Trakkr connection flow.
