=== Numative Analytics ===
Contributors: numative
Tags: analytics, privacy, ai, crawlers, seo
Requires at least: 5.6
Requires PHP: 7.2
Stable tag: 2.1.0
License: GPLv2 or later

Connect WordPress to Numative: privacy-friendly analytics with no theme edits,
AI crawler tracking that works behind page caches, and instant change pings.

== Description ==

The official Numative plugin. One install covers everything WordPress needs:

= Your dashboard, inside wp-admin =

A top-level **Numative** menu shows your analytics without leaving WordPress:
visitors, visits, pageviews, bounce rate and visit duration, a traffic chart,
and your top pages and sources — switchable between today / 7 / 30 / 90 days /
12 months. A compact widget on the WordPress Dashboard shows the last 7 days
at a glance. Data comes from the Numative Stats API using your API key —
nothing is made public, there are no iframes, and no JavaScript libraries are
loaded in your admin.

= Analytics snippet =

Tick one box and the cookieless, privacy-friendly Numative tracking script is
added to every front-end page — no theme edits, no code. Logged-in editors and
admins are excluded automatically so your own browsing never skews stats.

= AI crawler tracking =

AI crawlers (GPTBot, ClaudeBot, PerplexityBot…) don't execute JavaScript, so a
snippet never records them. The plugin detects crawler requests server-side by
User-Agent and forwards them to your Numative site — which bots, which pages
they read, verified vs. claimed — in the Bots & AI crawlers report.

On a cache HIT, WordPress/PHP doesn't run, which would hide cached crawler
visits. The plugin fixes that by telling your page cache to **never cache
AI-bot user-agents**, so PHP always runs for crawlers and every visit is
captured — no server-log access needed.

* WP Rocket and LiteSpeed Cache are configured automatically.
* For W3 Total Cache, WP Super Cache, or WP Fastest Cache, paste the user-agent
  list shown on the plugin's settings screen into that plugin's
  "Never cache the following user agents" setting (a one-time step).

If your site is served through an edge CDN (e.g. Cloudflare) that caches at the
edge, requests may never reach your server. In that case use Numative's
Cloudflare Worker instead (see your site's AI crawler tracking setup in
Numative). This plugin covers everything served from your origin.

= Instant recrawl ping =

The moment a post is published, updated, or unpublished, the plugin notifies
Numative (non-blocking) so the page is snapshotted within seconds — new
content, edits, and removals show up as chart markers with their exact time
instead of waiting for the next crawl.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` and activate it
   (or install the .zip via Plugins → Add New → Upload).
2. In Numative, open your site → Settings and copy your Site ID. For AI crawler
   tracking also click "Generate ingest key"; for instant pings create a
   write-scoped API key (or reuse the ingest key).
3. In WordPress, go to Numative → Settings, paste the values, tick the
   features you want, and save. Your analytics appear under the Numative menu
   and on the WordPress Dashboard.
4. If you use W3TC / WP Super Cache / WP Fastest Cache, paste the user-agent
   list from the settings screen into your cache plugin's "never cache user
   agents".

Performance: the snippet is a ~1 KB deferred script; the crawler capture only
makes a network call on detected bot requests and is non-blocking; the publish
ping is non-blocking too. Human page loads and response times are unaffected.

== Changelog ==

= 2.1.0 =
* New: full analytics dashboard inside wp-admin (top-level Numative menu) —
  stat tiles, traffic chart, top pages and top sources with a period switcher,
  server-rendered with inline SVG (no external scripts), cached 5 minutes.
* New: WordPress Dashboard widget with the last 7 days at a glance.
* Settings moved to Numative → Settings.

= 2.0.0 =
* Rebranded from "Numative — AI Crawler Tracking" to the general Numative
  Analytics plugin (settings moved to Settings → Numative; all saved options
  carry over unchanged).
* New: one-checkbox tracking snippet injection — run Numative analytics with
  no theme edits. Logged-in editors/admins are excluded.
* New: instant ping now also fires when a published post is edited (not just
  published/unpublished), so content updates are detected at their exact time.

= 1.1.0 =
* New: optional instant recrawl ping — when a post is published or unpublished,
  the plugin notifies Numative (non-blocking) so the page is re-crawled within
  seconds. Enable it on the settings screen; uses the optional API key field or
  falls back to the ingest key.

= 1.0.0 =
* Initial release: server-side AI crawler capture with cache-bypass-for-bots.
