=== Readable – AI Agent Analytics ===
Contributors: tryreadable
Tags: ai analytics, ai agents, chatgpt, perplexity, analytics
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Discover how AI tools find your website, which pages draw their interest, and where AI referrals land—all from your WordPress dashboard.

== Description ==

Understand how AI tools reach your WordPress site.

Which AI crawlers are reaching your content? Which pages receive visits referred by ChatGPT, Claude, Perplexity, Gemini, Microsoft Copilot, and other supported AI tools?

Readable brings these signals into a seven-day dashboard in WordPress, giving marketers a clear view of AI activity around their content.

= See what is happening =

* View recognised AI crawler requests and AI referral visits separately.
* Find the top AI sources and pages receiving activity.
* Follow daily trends over the past seven days.
* Review recent activity in one place.

Supported AI referral sources include ChatGPT, Claude, Perplexity, Gemini, and Microsoft Copilot. The dashboard recognises supported AI and search crawler signatures.

= Find the content getting noticed =

See which pages AI tools explore and where AI referrals land. Use these insights to guide your next content review and keep track of AI activity over time.

= Set up your site =

Install the plugin and choose **Connect to Readable** in its settings. Sign in or create a free Readable account, then confirm the WordPress site, limited data access, and that connecting starts analytics collection. After a successful connection, analytics collection starts automatically and you return to WordPress. An administrator can pause collection or disconnect at any time. Existing installed sites that are already paused remain paused until an administrator resumes or reconnects them. Your WordPress Address must use HTTPS, and its exact hostname must be enabled for analytics in Readable.

Matching completed requests are placed in a durable local queue and sent to Readable in the background. Your visitor response does not wait for Readable. Dashboard reads are cached locally for five minutes and can be refreshed by an administrator.

= What the plugin sends =

For matching visits only, the plugin sends:

* The configured Readable Site ID.
* HTTPS hostname and path, without query strings or fragments.
* A recognized AI agent user agent, or a fixed generic value for an AI-referred person.
* A normalized AI referral source, never the raw referral URL.
* Request time, response status, content type, duration, and random event identity.

The plugin does not send IP addresses, cookies, request or response bodies, authorization values, arbitrary headers, raw query strings, raw referral URLs, or full browser user agents for AI-referred people.

= External service =

This plugin sends the limited analytics data described above to Readable's ingestion service at `https://ingest.sonicadn.com/v1.0/traffic/data/wordpress`. This service is required for the plugin's analytics functionality. Data is sent only after a valid Readable Site ID and WordPress analytics key have been configured through the consented Connect flow and collection is active. An administrator can pause collection at any time.

The plugin also requests the site's aggregated analytics from `https://www.tryreadable.ai/api/external-agentic/integrations/wordpress/analytics` when an administrator opens or refreshes the plugin settings page. The saved WordPress analytics key is sent in the HTTPS authorization header. The service derives the Readable site from that key and returns only the site's bounded seven-day WordPress analytics; it does not accept a site ID from the browser for this read.

During an administrator-initiated Connect flow, the plugin contacts Readable's setup service at `https://www.tryreadable.ai/api/external-agentic/integrations/wordpress/pairing/start`, `/pairing/status`, and `/pairing/exchange`. It sends the WordPress site and callback URLs, random short-lived request and ownership tokens, a one-way verifier challenge, and a random plugin installation identifier so Readable can preserve the request, confirm site control, return safely to WordPress, and deliver the scoped credential without copying it. Status and exchange send the saved temporary request binding; the permanent key is returned only in the no-store HTTPS exchange response and is then encrypted in WordPress. These calls occur only after an administrator chooses Connect, Check status, Resume, or Start a new request.

When an administrator chooses Disconnect, the plugin contacts `https://www.tryreadable.ai/api/external-agentic/integrations/wordpress/pairing/disconnect` with the saved key in the HTTPS authorization header so Readable can revoke that plugin connection before WordPress removes its local credentials.

Readable privacy policy: https://www.tryreadable.ai/privacy

Readable terms: https://www.tryreadable.ai/terms

Product and setup information: https://www.tryreadable.ai/integrations/wordpress

== Installation ==

1. Install and activate **Readable – AI Agent Analytics**.
2. In WordPress, open **Settings → Readable Agent Analytics**.
3. Choose **Connect to Readable**. Sign in or create an account in the hosted Readable window.
4. Confirm the Readable account, exact WordPress hostname, limited analytics data access, and that connecting starts analytics collection. Readable verifies site control and returns to WordPress automatically.
5. WordPress exchanges a short-lived one-time code, stores the Site ID and scoped key encrypted, and starts collection; neither value needs to be copied.
6. Review the privacy boundary. You can pause collection without disconnecting, or disconnect and revoke the plugin key at any time.

Your WordPress Address must use HTTPS, and its exact hostname must be enabled for analytics in Readable.

== Screenshots ==

1. AI audience overview with fictional sample data, showing seven-day metrics and daily activity.
2. Top AI sources and pages using fictional sample data.
3. Recent activity using fictional sample data.
4. Connect, pause, retry, and delivery status using placeholder identifiers and fictional sample data.

== Frequently Asked Questions ==

= Does this slow down my website? =

Readable is never called while generating the visitor's page response. Matching completed requests are first written to a local WordPress database queue. WP-Cron sends bounded batches later.

= Does it collect every visitor? =

No. The plugin queues only recognized AI agents and visits whose referrer hostname belongs to a supported AI assistant.

= Does the dashboard show unique visitors? =

No. The dashboard counts detected requests and AI referral visits. A crawler fetching a page is different from a person opening a link from an AI tool, and repeated requests can be counted more than once. The figures do not identify unique people.

= Will it record requests served entirely by a page cache or CDN? =

Not always. The plugin records requests that reach WordPress and run PHP. A full-page cache or CDN can serve a response before WordPress runs, so those cache hits are outside the plugin's coverage. Sites that need edge-wide coverage should use analytics from their CDN or reverse proxy as well.

= Does recognition prove which company operated an agent? =

No. Recognition is based on request user-agent, referral-host, and supported agent-signature signals. Those values can be spoofed, so the dashboard is useful traffic evidence, not cryptographic identity verification.

= Does it track conversions or citations in AI answers? =

No. The plugin does not prove sales, leads, or other conversions, and it does not show whether your brand or page was mentioned or cited in an AI answer. It reports supported crawler requests and visits referred from supported AI tools that reach WordPress.

= Will installing the plugin improve my search or AI rankings? =

No. The plugin provides analytics evidence for your content reviews. It does not change your content or guarantee search rankings, AI visibility, mentions, or citations.

= Does it collect personal data? =

The plugin is designed to exclude IP addresses, cookies, bodies, query strings, raw referral URLs, and browser fingerprints for referred people. Site owners remain responsible for describing their use of analytics in their own privacy notice where required.

= What happens when Readable is unavailable? =

Events remain in the local queue and are retried with bounded exponential backoff. Unsent rows expire after 30 days. Rejected events are moved aside so they cannot block newer traffic and expire after 14 days. Cleanup removes at most 1,000 expired rows per run. The queue is capped at 50,000 rows; when it is full, recent retryable events are preserved and the plugin visibly reports new events that could not be stored.

= How do I get a Site ID and key? =

Open **Settings → Readable Agent Analytics** and choose **Connect to Readable**. A free account can verify one WordPress site through a short-lived, request-bound flow. The plugin receives its Site ID and scoped key through a server-to-server exchange and stores the key encrypted. Each site has one active key bound to its Readable WordPress integration; reconnecting revokes the previous one.

== Support ==

For setup and product guidance, visit https://www.tryreadable.ai/integrations/wordpress. For bug reports and support questions, use the **Support** tab on this plugin's WordPress.org page. Do not post Site IDs, API keys, or visitor data in the public support forum.

== Changelog ==

= 1.2.0 =

* Added hosted Connect with Readable sign-in/signup, site and data confirmation, automatic ownership verification, and encrypted credential return without copying keys.
* Analytics collection starts after the administrator confirms Connect and can be paused without disconnecting.
* Added a secure reconnect action that keeps the current connection until a verified replacement succeeds.
* Added safe retry and recovery for cancelled, expired, interrupted, and logged-out callback flows.
* Added explicit setup, status, exchange, dashboard, ingestion, and disconnect service disclosures.

= 1.1.0 =

* Added a seven-day AI audience dashboard inside WordPress.
* Added bounded top-source, top-page, daily activity, and recent-activity views.
* Added a separate read permission to WordPress integration keys; ingestion remains on SonicADN.
* Added explicit opt-in, WordPress Privacy Policy helper text, bounded retention, visible queue limits, and daily cleanup.
* Added free self-service setup with a short-lived WordPress-admin ownership challenge and one-time site key reveal.

= 1.0.0 =

* Initial public release.
* Durable, asynchronous delivery to Readable's dedicated WordPress ingestion edge.
* Privacy-safe AI agent and AI referral classification.
* Exact acknowledgement validation, retry backoff, and rejected-event quarantine.
