From 375dd916a98fcf0f02025d0462b56b669c4801aa Mon Sep 17 00:00:00 2001
From: Chris Portscheller
Date: Sun, 15 Nov 2026 20:13:27 -0600
Subject: [PATCH] Show visits sent by AI assistants without an account
AI referral counts were kept only on sites connected to WebDecoy Cloud and
shown only there. Every install now keeps daily counts per AI product and
landing page for 30 days and shows them on the dashboard widget (7 days)
and the Statistics page (30 days). Counts only: nothing about a visitor.
Connected sites still send their counts to WebDecoy Cloud as before.
---
admin/partials/dashboard-widget.php | 28 ++++
admin/partials/statistics-page.php | 52 +++++++
includes/class-webdecoy-activator.php | 22 ++-
includes/class-webdecoy-ai-referrals.php | 185 +++++++++++++++++++++--
tests/AiReferralLocalTest.php | 118 +++++++++++++++
uninstall.php | 3 +
webdecoy.php | 7 +-
7 files changed, 400 insertions(+), 15 deletions(-)
create mode 100644 tests/AiReferralLocalTest.php
diff --git a/admin/partials/dashboard-widget.php b/admin/partials/dashboard-widget.php
index 0b4c11f..8d735b5 100644
--- a/admin/partials/dashboard-widget.php
+++ b/admin/partials/dashboard-widget.php
@@ -27,6 +27,16 @@
set_transient('webdecoy_dashboard_crawlers', $crawlers, 5 * MINUTE_IN_SECONDS);
}
+// Page visits AI products (ChatGPT, Perplexity, Claude...) sent over 7 days.
+// Counted locally on every install (WebDecoy_AI_Referrals).
+$ai_referrals = get_transient('webdecoy_dashboard_ai_referrals');
+if ($ai_referrals === false) {
+ $ai_referrals = class_exists('WebDecoy_AI_Referrals')
+ ? WebDecoy_AI_Referrals::summary(7)
+ : ['total' => 0, 'platforms' => [], 'pages' => []];
+ set_transient('webdecoy_dashboard_ai_referrals', $ai_referrals, 5 * MINUTE_IN_SECONDS);
+}
+
$request_counts_today = WebDecoy_Request_Counts::summary(1);
// Checkout bot signals in the last 24 hours: velocity, card-testing patterns,
@@ -126,6 +136,24 @@
+
diff --git a/includes/class-webdecoy-activator.php b/includes/class-webdecoy-activator.php
index 3070653..28f2ca5 100644
--- a/includes/class-webdecoy-activator.php
+++ b/includes/class-webdecoy-activator.php
@@ -21,7 +21,7 @@ class WebDecoy_Activator
/**
* Database version for migrations
*/
- private const DB_VERSION = '2.11.1';
+ private const DB_VERSION = '2.13.0';
/**
* Plugin activation
@@ -165,6 +165,19 @@ private static function create_tables(): bool
PRIMARY KEY (bucket, outcome)
) $charset_collate;";
+ // Local AI referral counts (2.13.0): page visits AI products sent, per
+ // UTC day, platform and landing path, kept 30 days for the widget and
+ // Statistics page with no account. Counts only; nothing about a
+ // visitor. path_key is sha1(landing_path) for index limits.
+ $sql_ai_referral_days = "CREATE TABLE IF NOT EXISTS {$wpdb->prefix}webdecoy_ai_referral_days (
+ day DATE NOT NULL,
+ platform VARCHAR(50) NOT NULL,
+ path_key CHAR(40) NOT NULL,
+ landing_path VARCHAR(500) NOT NULL,
+ referrals BIGINT UNSIGNED NOT NULL DEFAULT 0,
+ PRIMARY KEY (day, platform, path_key)
+ ) $charset_collate;";
+
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
dbDelta($sql_blocked);
@@ -174,6 +187,7 @@ private static function create_tables(): bool
dbDelta($sql_violation_queue);
dbDelta($sql_ai_referrals);
dbDelta($sql_crawler_visits);
+ dbDelta($sql_ai_referral_days);
dbDelta($sql_request_counts);
$table = $wpdb->prefix . 'webdecoy_request_counts';
$exists = $wpdb->get_var($wpdb->prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table))) === $table;
@@ -303,6 +317,7 @@ public static function uninstall(): void
$wpdb->prefix . 'webdecoy_ai_referrals',
$wpdb->prefix . 'webdecoy_crawler_visits',
$wpdb->prefix . 'webdecoy_request_counts',
+ $wpdb->prefix . 'webdecoy_ai_referral_days',
];
foreach ($tables as $table) {
@@ -359,6 +374,11 @@ public static function uninstall(): void
WebDecoy_Crawler_Visits::prune();
}
+ // Local AI referral counts keep 30 days.
+ if (class_exists('WebDecoy_AI_Referrals')) {
+ WebDecoy_AI_Referrals::prune();
+ }
+
if (class_exists('WebDecoy_Request_Counts')) {
WebDecoy_Request_Counts::prune();
}
diff --git a/includes/class-webdecoy-ai-referrals.php b/includes/class-webdecoy-ai-referrals.php
index d75cde7..b42c390 100644
--- a/includes/class-webdecoy-ai-referrals.php
+++ b/includes/class-webdecoy-ai-referrals.php
@@ -16,10 +16,13 @@
* metadata says it is a document navigation. Pages served from a full-page
* cache never reach PHP and are not counted, so the figure is a floor.
*
- * Counts accumulate in one small table and are sent every fifteen minutes when
- * the site is connected to WebDecoy Cloud. Each send claims the open counts
- * under a batch id; a failed send keeps that id and is retried with it, and
- * WebDecoy counts a batch id once.
+ * Every install keeps its own daily counts (platform, landing path, number)
+ * for {@see self::LOCAL_RETENTION_DAYS} days, shown on the dashboard widget and
+ * the Statistics page with no account. When the site is also connected to
+ * WebDecoy Cloud, counts accumulate in a second small table and are sent every
+ * fifteen minutes. Each send claims the open counts under a batch id; a failed
+ * send keeps that id and is retried with it, and WebDecoy counts a batch id
+ * once.
*/
class WebDecoy_AI_Referrals
{
@@ -31,6 +34,21 @@ class WebDecoy_AI_Referrals
/** Distinct platform and path pairs kept before new ones are dropped. */
private const MAX_ROWS = 5000;
+ /** The schema version that created the local daily table. Recording waits for it. */
+ public const SINCE_DB_VERSION = '2.13.0';
+ /** Days of local daily counts kept. */
+ public const LOCAL_RETENTION_DAYS = 30;
+ /**
+ * Distinct landing paths kept per day. Past it a referral still counts for
+ * its platform, under an empty path, so platform totals stay exact.
+ */
+ private const MAX_PATHS_PER_DAY = 1000;
+
+ /** True once register() has turned counting on. */
+ private static bool $counting = false;
+ /** True when counts are also queued for WebDecoy Cloud. */
+ private static bool $cloud = false;
+
/**
* The ai_referrals table name, prefixed and escaped for interpolation.
*/
@@ -40,22 +58,39 @@ public static function table(): string
return esc_sql($wpdb->prefix . 'webdecoy_ai_referrals');
}
+ /** The local daily counts table name, prefixed and escaped for interpolation. */
+ public static function days_table(): string
+ {
+ global $wpdb;
+ return esc_sql($wpdb->prefix . 'webdecoy_ai_referral_days');
+ }
+
/**
- * Whether counting runs: connected to WebDecoy Cloud, and not turned off
- * with the webdecoy_count_ai_referrals filter.
+ * Whether counting runs at all: on unless turned off with the
+ * webdecoy_count_ai_referrals filter. Needs no account.
*/
- public static function enabled(string $apiKey): bool
+ public static function enabled(): bool
{
- return $apiKey !== '' && (bool) apply_filters('webdecoy_count_ai_referrals', true);
+ return (bool) apply_filters('webdecoy_count_ai_referrals', true);
}
- /** Wire the counter and its flush, scheduling the flush if it is not. */
+ /**
+ * Wire the counter. Counts are always kept locally; with an API key they
+ * are also sent to WebDecoy Cloud, and the flush is scheduled.
+ */
public static function register(string $apiKey): void
{
- if (!self::enabled($apiKey)) {
+ self::$counting = false;
+ self::$cloud = false;
+ if (!self::enabled()) {
return;
}
+ self::$counting = true;
add_action('template_redirect', [self::class, 'observe'], 1);
+ self::$cloud = $apiKey !== '';
+ if (!self::$cloud) {
+ return;
+ }
add_action(self::CRON_HOOK, static function () use ($apiKey): void {
self::flush($apiKey);
});
@@ -67,6 +102,9 @@ public static function register(string $apiKey): void
/** Count the current request if it is a page visit an AI product sent. */
public static function observe(): void
{
+ if (!self::$counting) {
+ return;
+ }
// phpcs:disable WordPress.Security.ValidatedSanitizedInput -- compared and classified, never stored or echoed
$method = strtoupper((string) ($_SERVER['REQUEST_METHOD'] ?? ''));
$mode = (string) ($_SERVER['HTTP_SEC_FETCH_MODE'] ?? '');
@@ -78,7 +116,132 @@ public static function observe(): void
if ($platform === '') {
return;
}
- self::increment($platform, self::landingPath($uri));
+ $path = self::landingPath($uri);
+ self::recordDay($platform, $path);
+ if (self::$cloud) {
+ self::increment($platform, $path);
+ }
+ }
+
+ /** The UTC day a timestamp counts against. Pure, for tests. */
+ public static function day(int $timestamp): string
+ {
+ return gmdate('Y-m-d', $timestamp);
+ }
+
+ /**
+ * Count one referral in the local daily table, bounded to
+ * {@see self::MAX_PATHS_PER_DAY} landing paths a day.
+ */
+ private static function recordDay(string $platform, string $path): void
+ {
+ if (!self::localReady()) {
+ return;
+ }
+ global $wpdb;
+ $table = self::days_table();
+ $day = self::day(time());
+ // phpcs:disable WordPress.DB.DirectDatabaseQuery, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- table name from $wpdb->prefix
+ $known = (int) $wpdb->get_var($wpdb->prepare(
+ "SELECT COUNT(*) FROM {$table} WHERE day = %s AND platform = %s AND path_key = %s",
+ $day,
+ $platform,
+ sha1($path)
+ ));
+ if ($known === 0) {
+ $paths = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM {$table} WHERE day = %s", $day));
+ if ($paths >= self::MAX_PATHS_PER_DAY) {
+ $path = '';
+ }
+ }
+ $wpdb->query($wpdb->prepare(
+ "INSERT INTO {$table} (day, platform, path_key, landing_path, referrals) VALUES (%s, %s, %s, %s, 1)
+ ON DUPLICATE KEY UPDATE referrals = referrals + 1",
+ $day,
+ $platform,
+ sha1($path),
+ $path
+ ));
+ // phpcs:enable
+ }
+
+ /**
+ * Referrals over the last N days (today included), for the dashboard
+ * widget and the Statistics page.
+ *
+ * @return array{total:int,platforms:list
,pages:list}
+ */
+ public static function summary(int $days): array
+ {
+ if (!self::localReady()) {
+ return self::summarize([]);
+ }
+ global $wpdb;
+ $table = self::days_table();
+ // phpcs:disable WordPress.DB.DirectDatabaseQuery, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- table name from $wpdb->prefix
+ $rows = $wpdb->get_results($wpdb->prepare(
+ "SELECT platform, landing_path, SUM(referrals) AS referrals FROM {$table} WHERE day >= %s GROUP BY platform, landing_path",
+ self::day(time() - (max(1, $days) - 1) * DAY_IN_SECONDS)
+ ), ARRAY_A);
+ // phpcs:enable
+ return self::summarize(is_array($rows) ? $rows : []);
+ }
+
+ /**
+ * Fold daily rows into a total, per-platform counts and per-page counts,
+ * busiest first. Rows past the daily path bound have an empty path: they
+ * count for their platform but name no page. Pure, for tests.
+ *
+ * @param list $rows
+ * @return array{total:int,platforms:list,pages:list}
+ */
+ public static function summarize(array $rows): array
+ {
+ $total = 0;
+ $platforms = [];
+ $pages = [];
+ foreach ($rows as $row) {
+ $platform = (string) ($row['platform'] ?? '');
+ $path = (string) ($row['landing_path'] ?? '');
+ $n = (int) ($row['referrals'] ?? 0);
+ if ($platform === '' || $n <= 0) {
+ continue;
+ }
+ $total += $n;
+ $platforms[$platform] = ($platforms[$platform] ?? 0) + $n;
+ if ($path !== '') {
+ $pages[$path] = ($pages[$path] ?? 0) + $n;
+ }
+ }
+ $byCount = static function (array $counts, string $key): array {
+ $list = [];
+ foreach ($counts as $name => $n) {
+ $list[] = [$key => (string) $name, 'referrals' => $n];
+ }
+ usort($list, static function (array $a, array $b) use ($key): int {
+ return $b['referrals'] <=> $a['referrals'] ?: strcmp($a[$key], $b[$key]);
+ });
+ return $list;
+ };
+ return ['total' => $total, 'platforms' => $byCount($platforms, 'platform'), 'pages' => $byCount($pages, 'path')];
+ }
+
+ /** Delete local daily counts older than the retention window. */
+ public static function prune(): void
+ {
+ if (!self::localReady()) {
+ return;
+ }
+ global $wpdb;
+ $table = self::days_table();
+ // phpcs:ignore WordPress.DB.DirectDatabaseQuery, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- table name from $wpdb->prefix
+ $wpdb->query($wpdb->prepare("DELETE FROM {$table} WHERE day < %s", self::day(time() - self::LOCAL_RETENTION_DAYS * DAY_IN_SECONDS)));
+ }
+
+ /** Whether the local daily table exists yet (the schema upgrade has run). */
+ private static function localReady(): bool
+ {
+ return version_compare((string) get_option('webdecoy_db_version', '0'), self::SINCE_DB_VERSION, '>=');
}
/**
diff --git a/tests/AiReferralLocalTest.php b/tests/AiReferralLocalTest.php
new file mode 100644
index 0000000..0199591
--- /dev/null
+++ b/tests/AiReferralLocalTest.php
@@ -0,0 +1,118 @@
+ */
+ public $inserts = [];
+
+ public function prepare($sql, ...$args) { return vsprintf(str_replace(['%d', '%s'], ['%d', "'%s'"], $sql), $args); }
+ public function get_var($sql) { return 0; }
+ public function query($sql)
+ {
+ if (preg_match('/INSERT INTO (\S+)/', $sql, $m)) {
+ $this->inserts[] = $m[1];
+ }
+ return true;
+ }
+}
+
+$t = ['TestRunner', 'test'];
+$same = ['TestRunner', 'assertSame'];
+
+/** Observe one ChatGPT page visit with a given API key; return the tables written. */
+function wd_observe_referral(string $apiKey, string $dbVersion): array
+{
+ $db = new WdFakeReferralDb();
+ $GLOBALS['wpdb'] = $db;
+ $GLOBALS['__wd_opts']['webdecoy_db_version'] = $dbVersion;
+ $_SERVER['REQUEST_METHOD'] = 'GET';
+ $_SERVER['HTTP_SEC_FETCH_MODE'] = 'navigate';
+ $_SERVER['HTTP_SEC_FETCH_DEST'] = 'document';
+ $_SERVER['HTTP_REFERER'] = 'https://chatgpt.com/c/1';
+ $_SERVER['REQUEST_URI'] = '/pricing?x=1';
+ WebDecoy_AI_Referrals::register($apiKey);
+ WebDecoy_AI_Referrals::observe();
+ unset($_SERVER['HTTP_SEC_FETCH_MODE'], $_SERVER['HTTP_SEC_FETCH_DEST'], $_SERVER['HTTP_REFERER']);
+ return $db->inserts;
+}
+
+$t('an AI referral is counted locally with no account, and not queued for the cloud', function () use ($same) {
+ $same(wd_observe_referral('', '2.13.0'), ['wp_webdecoy_ai_referral_days']);
+});
+
+$t('a connected site counts locally and queues for the cloud', function () use ($same) {
+ $same(wd_observe_referral('key', '2.13.0'), ['wp_webdecoy_ai_referral_days', 'wp_webdecoy_ai_referrals']);
+});
+
+$t('local counting waits for the table to exist', function () use ($same) {
+ $same(wd_observe_referral('', '2.11.1'), []);
+});
+
+$t('the summary totals by platform and page, busiest first', function () use ($same) {
+ $s = WebDecoy_AI_Referrals::summarize([
+ ['platform' => 'Perplexity', 'landing_path' => '/blog/a', 'referrals' => '2'],
+ ['platform' => 'ChatGPT', 'landing_path' => '/pricing', 'referrals' => '5'],
+ ['platform' => 'ChatGPT', 'landing_path' => '/blog/a', 'referrals' => 1],
+ // Past the daily path bound: counts for the platform, names no page.
+ ['platform' => 'ChatGPT', 'landing_path' => '', 'referrals' => 3],
+ ['platform' => '', 'landing_path' => '/x', 'referrals' => 9],
+ ['platform' => 'Claude', 'landing_path' => '/x', 'referrals' => 0],
+ ]);
+ $same($s['total'], 11);
+ $same($s['platforms'], [
+ ['platform' => 'ChatGPT', 'referrals' => 9],
+ ['platform' => 'Perplexity', 'referrals' => 2],
+ ]);
+ $same($s['pages'], [
+ ['path' => '/pricing', 'referrals' => 5],
+ ['path' => '/blog/a', 'referrals' => 3],
+ ]);
+});
+
+$t('the summary of nothing is empty', function () use ($same) {
+ $same(WebDecoy_AI_Referrals::summarize([]), ['total' => 0, 'platforms' => [], 'pages' => []]);
+});
diff --git a/uninstall.php b/uninstall.php
index 5a06df3..b158af7 100644
--- a/uninstall.php
+++ b/uninstall.php
@@ -35,6 +35,7 @@
$wpdb->prefix . 'webdecoy_ai_referrals',
$wpdb->prefix . 'webdecoy_request_counts',
$wpdb->prefix . 'webdecoy_crawler_visits',
+ $wpdb->prefix . 'webdecoy_ai_referral_days',
];
foreach ($tables as $table) {
@@ -90,6 +91,8 @@
$wpdb->prefix . 'webdecoy_checkout_attempts',
$wpdb->prefix . 'webdecoy_ai_referrals',
$wpdb->prefix . 'webdecoy_request_counts',
+ $wpdb->prefix . 'webdecoy_crawler_visits',
+ $wpdb->prefix . 'webdecoy_ai_referral_days',
];
foreach ($tables as $table) {
diff --git a/webdecoy.php b/webdecoy.php
index 5f4798e..ccaf2dd 100644
--- a/webdecoy.php
+++ b/webdecoy.php
@@ -979,8 +979,9 @@ private function init_hooks(): void
// Safety-net cron drain of the violation-report spool.
add_action('webdecoy_flush_violations', [$this, 'cron_flush_violations']);
- // AI referral counting, when connected to WebDecoy Cloud: visits AI
- // products send, as aggregate counts for the AI Traffic page. Wired on
+ // AI referral counting: visits AI products send, as aggregate counts,
+ // kept locally on every install and also sent to WebDecoy Cloud's AI
+ // Traffic page when connected. Wired on
// plugins_loaded because its class is loaded there by load_includes().
add_action('plugins_loaded', [$this, 'register_ai_referrals'], 20);
@@ -1380,7 +1381,7 @@ private function build_rule_engine(): ?\WebDecoy\Rules\RuleEngine
}
/**
- * Register AI referral counting (a no-op unless connected to WebDecoy Cloud).
+ * Register AI referral counting: always local, and sent to WebDecoy Cloud when connected.
*/
public function register_ai_referrals(): void
{