=== Tactical — AI Agent Detection for WooCommerce ===
Contributors: sourabhnk
Tags: woocommerce, ai, analytics, chatgpt, perplexity
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Detects AI crawlers even when they don't run JavaScript (most don't) — plus which AI fetched which products, and what converts.

== Description ==

Most AI retrieval crawlers — the bots that feed ChatGPT, Perplexity, Claude, and Google's AI answers — **do not run JavaScript**, so JavaScript-only analytics (including standard site analytics) never see them. This plugin adds **server-side detection**: when a known AI crawler requests a page, Tactical records it — no JavaScript required. Human visitors are untouched (an event fires only on a matched AI user-agent), so there's zero measurable impact on page speed.

AI shopping agents and crawlers from ChatGPT, Perplexity, Claude, and Google AI visit your storefront every day — fetching products, comparing prices, deciding what to recommend. This plugin makes that traffic visible: which AI fetched which product pages, what shopping agents did on-site, and which humans arrived from AI answers.

This plugin connects your WooCommerce store to **Tactical**, a third-party agent-traffic intelligence service operated at https://tactical-app.work. The plugin handles install, snippet injection, and WooCommerce webhook registration; the dashboard, alerts, and reporting live in your Tactical account on tactical-app.work.

**What you get:**

* **Agent Traffic Monitor** — real-time counts of agent visits broken down by agent type, day, and product
* **Agent browsers** — agent browsers that don't name themselves, like Meta's Muse, are scored on how the session behaves
* **Intent Signals** — score every session by browse vs. buy intent; compare agent vs. human conversion
* **Competitive Exposure** *(paid plans)* — see which competitors are sending agents to check your prices

**Why agent traffic matters now:**

Standard analytics filter agent traffic out as "bot noise". As of Q2 2026, AI agents make up an estimated 8–12% of e-commerce site visits — and that share is growing month over month. The merchants who see this traffic are the ones positioned to capture the buyers it represents.

**Tactical pricing — managed at tactical-app.work:**

Tactical is a tiered SaaS product. The plugin works on every tier, including the free one.

* **Scout — $0/mo (free forever)** — Tactical's free tier. 100 agent sessions/week, top 3 agent types, weekly intelligence brief. No credit card.
* **Radar — $39/mo** — 90-day history, all agent types, intent signals, product interest map (10,000 sessions/mo)
* **Command — $129/mo** — competitive exposure, revenue leakage estimates, custom competitor tracking, unlimited products (50,000 sessions/mo)

Annual plans save ~25%.

**Multi-platform:**

This plugin is for WooCommerce. The same Tactical account also works on Shopify (via the Shopify App Store) and on any custom storefront (via JS snippet at tactical-app.work).

== Installation ==

1. Upload the `tactical-agent-detection` folder to `/wp-content/plugins/`, or install via the Plugins → Add New screen.
2. Activate the plugin. (WooCommerce must be installed and active first; this plugin declares it as a required dependency.)
3. Sign up at https://tactical-app.work and copy your API key from the dashboard.
4. Go to Settings → Tactical and paste the API key.
5. Click "Verify connection" — you should see a green checkmark.
6. Open your storefront — Tactical starts classifying agent traffic immediately.

The plugin auto-registers WooCommerce webhooks for `order.created`, `order.updated`, `product.created`, and `product.updated` so order and catalog activity is correlated with agent sessions.

== External services ==

This plugin connects to **Tactical** at https://tactical-app.work — a third-party agent-traffic intelligence service operated by the plugin author. The plugin requires an active Tactical account (free Scout tier is sufficient) to function. Without an API key configured on the settings page, no requests are made.

**Endpoints used:**

* **Snippet ingest** — `https://tactical-app.work/api/ingest`. The detection script (`https://tactical-app.work/snippet.js`) loads on every storefront page view and posts an event payload containing: an anonymised session ID, page URL (path + query string only), referrer domain, user-agent string, scroll/mouse/timing heuristics, and your store's API key. No customer PII (no names, emails, IP addresses, payment data, or form contents) is sent.
* **Connection verification** — `https://tactical-app.work/api/verify-connection`. Triggered only when an admin clicks "Verify connection" on the settings page. Sends only your API key (in a request header) so Tactical can confirm the key belongs to this store. No event data.
* **WooCommerce webhooks** — `https://tactical-app.work/api/wc-webhook/<topic>`. Once an API key is saved, four webhook subscriptions are registered with WooCommerce (`order.created`, `order.updated`, `product.created`, `product.updated`). WooCommerce delivers these payloads directly to Tactical with WC's standard HMAC signature when matching events occur on your store. Payload contents are WooCommerce's standard webhook bodies (order or product objects).

**Conditions:** events are only sent after you paste a valid API key on the settings page. Without a key, the snippet does not load, no requests are made, and no webhooks are registered.

**Service terms:**

* Tactical Privacy Policy: https://tactical-app.work/privacy
* Tactical Terms of Service: https://tactical-app.work/terms

== Frequently Asked Questions ==

= Do I need a Tactical account to use this plugin? =

Yes — sign up free at tactical-app.work. The free Scout tier is 100 agent sessions per week with no credit card.

= What data does the plugin collect? =

The storefront script sends anonymised session metadata only: user-agent, page URL, referrer, scroll/mouse heuristics, and product context, with no names, emails, IP addresses or payment data. The order webhooks deliver WooCommerce's standard order body, which includes the customer's details; Tactical keeps only the order ID, total, currency, line items and how the order was attributed, uses the buyer's IP address and user-agent once to match the order to a session, and discards the rest.

= How is agent traffic detected? =

Tactical's edge classifier uses user-agent patterns, IP-derived signals (datacenter flag, country — the IP itself is not stored), request behaviour, and known agent fingerprints to identify ChatGPT, Perplexity, Claude, Google AI, and other AI agents in real time.

= What about agents that don't identify themselves, like Meta's Muse? =

A named crawler (GPTBot, PerplexityBot, ClaudeBot) says who it is in its user-agent, so server-side detection catches it outright. An agent browser — Meta's Muse, OpenAI's Operator — drives a real browser on a shopper's behalf, and it visits your store whether or not you're a commerce partner of theirs. No request-layer fingerprint for Muse has been published by anyone yet, so a user-agent list can't see it. Tactical's behavioural layer scores the session itself (page-timing regularity, interaction signals, browser environment). In a September 2026 test, an AI-driven browser scored as an agent and a person in Chrome on the same laptop scored as human; a real Muse session has not yet been confirmed. Tactical's agent registry tracks Muse as fingerprint research, and a confirmed signature goes live without waiting for a plugin release.

= Will this slow down my site? =

No. The storefront script loads asynchronously with the `defer` attribute and weighs under 5 KB, and classification happens at Tactical's edge, off your origin. Server-side crawler detection does nothing for human visitors — it only fires a lightweight, non-blocking request when a request's user-agent matches a known AI crawler, so real visitors incur no extra HTTP call and no measurable TTFB change.

= How do I cancel? =

Cancel from the Tactical dashboard's billing page at tactical-app.work. The plugin keeps working on the free Scout tier after cancellation.

= Where's my data stored? =

In Tactical's Postgres database (US/EU regions). Aggregated and purged on a 90-day rolling window.

= Is this GDPR-compliant? =

Tactical processes data under the legitimate-interest legal basis. We don't store PII or browser fingerprints, and merchants can request data deletion at any time from the dashboard or by emailing hello@tactical-app.work. A Data Processing Addendum is available on request.

== Screenshots ==

1. Plugin settings page — paste API key and verify connection.
2. Tactical dashboard at tactical-app.work showing real-time agent traffic.
3. Agent type breakdown by day.
4. Intent funnel — browse vs. evaluate vs. buy.

== Changelog ==

= 1.2.0 =
* **New: Tactical Gate.** Enforce the agent policy you set on tactical-app.work in the request path: throttle, require identification, challenge, redirect or block AI agents by identity, category, confidence and scope (paths, products, collections, cart, checkout, schedule). Fetches the compiled policy every five minutes with an ETag, applies it on page requests, add-to-cart and checkout, and reports decisions in batches.
* Every policy starts in Observe mode, where rules only tag. People are never restricted, whatever the policy says, and a search engine only when the policy names it and confirms the SEO impact. No policy, a failed fetch or any error means the request passes untouched.
* New settings toggle "Tactical Gate" (on by default; a no-op until a policy exists) with policy version, mode and last-fetch status.
* The settings page now recreates any missing Tactical webhooks (for example after WooCommerce was activated after this plugin), instead of asking you to reactivate.

= 1.1.0 =
* **New: server-side AI crawler detection.** Detects AI crawlers that don't run JavaScript (most retrieval crawlers) by matching the request user-agent against a maintained registry of AI operators (OpenAI, Anthropic, Perplexity, Google, Meta, Apple, Amazon, ByteDance, Mistral, DuckDuckGo, and more). Fires only on a matched AI user-agent — zero extra work, and zero measurable impact, for human visitors.
* Non-blocking delivery (`wp_remote_post` with `blocking => false`, 1s timeout) and a 60-second per-(agent, URL) dedup guard against crawler bursts.
* New settings toggle "Server-side AI crawler detection" (on by default) with a "last event sent" status line.
* Optional `tactical_trust_proxy_headers` filter to read the crawler's real IP from CDN/proxy headers when the store is behind Cloudflare or similar.

= 1.0.2 =
* Security: removed the `data-key` attribute from the storefront `<script>` tag. The Tactical API key is a server-side secret used to sign WooCommerce webhook deliveries and authenticate plugin-to-server API calls — it must not appear in browser-rendered HTML. The snippet identifies the tenant by `data-shop` plus the request Origin, so no key is required client-side. Recommended upgrade for all installs.

= 1.0.1 =
* Compliance: storefront snippet now loads via `wp_enqueue_script` with the `defer` strategy, decorated via the `script_loader_tag` filter. No more inline `<script>` injection.
* Compliance: settings-page admin JS extracted to `assets/admin-settings.js`, enqueued via `wp_enqueue_script` + `wp_localize_script`. No more inline `<script>` in the admin page.
* Compliance: declared `Requires Plugins: woocommerce` so WP correctly blocks activation without WooCommerce.
* Readme: added the "External services" disclosure, clarified Scout/Tactical naming in the pricing section, updated Contributors.
* Bumped `Requires at least` to WP 6.3 (needed for `wp_enqueue_script` defer/async strategy).

= 1.0.0 =
* Initial release.
* Snippet injection on the storefront when an API key is configured.
* Settings page with API key, store domain, and "Verify connection" button.
* Auto-registration of WooCommerce webhooks for order and product topics.
* Uninstall removes options + Tactical-managed webhooks.

== Upgrade Notice ==

= 1.1.0 =
Adds server-side detection of AI crawlers that don't run JavaScript — the majority of AI retrieval traffic. No impact on human visitors. Recommended.

= 1.0.2 =
Security fix — stops rendering the API key into storefront HTML. Recommended upgrade for all installs.

= 1.0.1 =
WP.org compliance pass — script enqueueing is now spec-compliant. No functional changes; safe to upgrade.

= 1.0.0 =
First public release.
