Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(traffic): store an anonymous visitor key instead of the visitor's IP address (#1410)

Gökhan Geyika527f9fdc665
diff --git a/server/src/lib/traffic-visits.js b/server/src/lib/traffic-visits.js
index 3bc61add9..5e65d2b03 100644
--- a/server/src/lib/traffic-visits.js
+++ b/server/src/lib/traffic-visits.js
@@ -3,10 +3,11 @@
*
* The snippet sends a beacon on every AI-referred page load, so a reload or a
* second link from the same answer arrives as another row. A visit is a
- * session, as Google Analytics counts one: the same visitor (IP address and
- * user agent) from the same AI platform, with less than VISIT_GAP_MINUTES
- * between pageviews. A different platform starts a new visit, as a new
- * traffic source starts a new session in GA4.
+ * session, as Google Analytics counts one: the same visitor (their
+ * anonymous key from visitor-key.js, and user agent) from the same AI
+ * platform, with less than VISIT_GAP_MINUTES between pageviews. A different
+ * platform starts a new visit, as a new traffic source starts a new session
+ * in GA4.
*
* The answer is stored on the row as `visit_of` (migration 00172, which
* grouped the rows stored before it with the same rule): null when the
@@ -22,17 +23,17 @@ export const VISIT_GAP_MINUTES = 30;
*
* The gap is measured from the visitor's latest pageview, not the visit's
* first, so a visit stays open while its pageviews keep coming. A pageview
- * with no IP address or user agent can't be matched to anyone's, so it
+ * with no visitor key or user agent can't be matched to anyone's, so it
* starts a visit of its own.
*/
export async function findVisitOf({
brandId,
sourcePlatform,
- ipAddress,
+ visitorKey,
userAgent,
now = Date.now(),
}) {
- if (!ipAddress || !userAgent) return null;
+ if (!visitorKey || !userAgent) return null;
const since = new Date(now - VISIT_GAP_MINUTES * 60_000).toISOString();
const { data, error } = await supabaseAdmin
@@ -40,7 +41,7 @@ export async function findVisitOf({
.select('id, visit_of')
.eq('brand_id', brandId)
.eq('source_platform', sourcePlatform)
- .eq('ip_address', ipAddress)
+ .eq('visitor_key', visitorKey)
.eq('user_agent', userAgent)
.gt('created_at', since)
.order('created_at', { ascending: false })
diff --git a/server/src/lib/traffic-visits.test.js b/server/src/lib/traffic-visits.test.js
index 47732b938..24012fe59 100644
--- a/server/src/lib/traffic-visits.test.js
+++ b/server/src/lib/traffic-visits.test.js
@@ -33,7 +33,7 @@ const NOW = Date.parse('2026-10-18T12:00:00.000Z');
const pageview = {
brandId: 'b1',
sourcePlatform: 'gemini.google.com',
- ipAddress: '203.0.113.7',
+ visitorKey: 'vk-1',
userAgent: 'Mozilla/5.0',
now: NOW,
};
@@ -56,7 +56,7 @@ describe('findVisitOf', () => {
['select', 'id, visit_of'],
['eq', 'brand_id', 'b1'],
['eq', 'source_platform', 'gemini.google.com'],
- ['eq', 'ip_address', '203.0.113.7'],
+ ['eq', 'visitor_key', 'vk-1'],
['eq', 'user_agent', 'Mozilla/5.0'],
['gt', 'created_at', '2026-10-18T11:30:00.000Z'],
['order', 'created_at', { ascending: false }],
@@ -76,7 +76,7 @@ describe('findVisitOf', () => {
});
it("starts a visit when it can't tell who the visitor is", async () => {
- expect(await findVisitOf({ ...pageview, ipAddress: null })).toBeNull();
+ expect(await findVisitOf({ ...pageview, visitorKey: null })).toBeNull();
expect(await findVisitOf({ ...pageview, userAgent: null })).toBeNull();
expect(db.calls).toEqual([]);
});
diff --git a/server/src/lib/visitor-key.js b/server/src/lib/visitor-key.js
new file mode 100644
index 000000000..a70280b2a
--- /dev/null
+++ b/server/src/lib/visitor-key.js
@@ -0,0 +1,45 @@
+/**
+ * An anonymous key for a tracking-snippet visitor, in place of their IP
+ * address (GDPR).
+ *
+ * The IP address is only needed to tell one visitor's pageviews from
+ * another's for half an hour (a visit, AT-003) and to find the pageview a
+ * not-found title belongs to. So it is never stored: the key is a one-way
+ * hash of the IP with the brand and a salt that changes every day. The
+ * database keeps each day's salt for two days only (traffic_salt, 00250);
+ * once a salt is gone, nothing links its keys to an address, and a visitor
+ * gets a new key every day, so their days can't be joined either.
+ */
+
+import { createHash } from 'node:crypto';
+import supabaseAdmin from '../config/supabase.js';
+
+let cached = null;
+
+/** Today's salt (UTC), read once a day; the database makes it on first use. */
+export async function dailySalt(now = new Date()) {
+ const day = now.toISOString().slice(0, 10);
+ if (cached?.day === day) return cached.salt;
+ const { data, error } = await supabaseAdmin.rpc('traffic_salt', { p_day: day });
+ if (error) throw new Error(error.message);
+ if (typeof data !== 'string' || !data) throw new Error('traffic_salt returned no salt');
+ cached = { day, salt: data };
+ return data;
+}
+
+/**
+ * The visitor's key for this brand today, or null without an IP address.
+ *
+ * @param {{ brandId: string, ip: string | null | undefined, now?: Date }} params
+ * @returns {Promise<string | null>} 64 hex characters
+ */
+export async function visitorKey({ brandId, ip, now = new Date() }) {
+ if (!ip) return null;
+ const salt = await dailySalt(now);
+ return createHash('sha256').update(`${salt}:${brandId}:${ip}`).digest('hex');
+}
+
+/** Forgets the cached salt (tests). */
+export function resetDailySalt() {
+ cached = null;
+}
diff --git a/server/src/lib/visitor-key.test.js b/server/src/lib/visitor-key.test.js
new file mode 100644
index 000000000..b8d9e4c1e
--- /dev/null
+++ b/server/src/lib/visitor-key.test.js
@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * The tracking snippet's visitor key (GDPR, 00250): a one-way key in place
+ * of the IP address, the same for a visitor all day, new the next.
+ */
+
+const rpc = vi.fn();
+vi.mock('../config/supabase.js', () => ({ default: { rpc: (...args) => rpc(...args) } }));
+
+const { visitorKey, resetDailySalt } = await import('./visitor-key.js');
+
+const TODAY = new Date('2026-10-23T09:00:00.000Z');
+const LATER_TODAY = new Date('2026-10-23T23:59:00.000Z');
+const TOMORROW = new Date('2026-10-24T00:01:00.000Z');
+
+beforeEach(() => {
+ resetDailySalt();
+ rpc.mockReset();
+ rpc.mockImplementation(async (_, { p_day }) => ({ data: `salt-${p_day}`, error: null }));
+});
+
+describe('visitorKey', () => {
+ it('gives a visitor one key all day, and never contains the address', async () => {
+ const morning = await visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: TODAY });
+ const night = await visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: LATER_TODAY });
+ expect(morning).toMatch(/^[0-9a-f]{64}$/);
+ expect(night).toBe(morning);
+ expect(morning).not.toContain('203.0.113.7');
+ });
+
+ it('reads the salt once a day', async () => {
+ await visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: TODAY });
+ await visitorKey({ brandId: 'b2', ip: '198.51.100.4', now: LATER_TODAY });
+ expect(rpc).toHaveBeenCalledTimes(1);
+ expect(rpc).toHaveBeenCalledWith('traffic_salt', { p_day: '2026-10-23' });
+ });
+
+ it('gives a new key the next day, for another brand and for another address', async () => {
+ const key = await visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: TODAY });
+ expect(await visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: TOMORROW })).not.toBe(key);
+ expect(await visitorKey({ brandId: 'b2', ip: '203.0.113.7', now: TODAY })).not.toBe(key);
+ expect(await visitorKey({ brandId: 'b1', ip: '203.0.113.8', now: TODAY })).not.toBe(key);
+ });
+
+ it('has no key without an address, and fails when there is no salt', async () => {
+ expect(await visitorKey({ brandId: 'b1', ip: null, now: TODAY })).toBeNull();
+ expect(rpc).not.toHaveBeenCalled();
+
+ rpc.mockResolvedValue({ data: null, error: { message: 'permission denied' } });
+ await expect(visitorKey({ brandId: 'b1', ip: '203.0.113.7', now: TODAY })).rejects.toThrow(
+ 'permission denied',
+ );
+ });
+});
diff --git a/server/src/routes/traffic-track.test.js b/server/src/routes/traffic-track.test.js
index d5e4989c6..22a0b44dc 100644
--- a/server/src/routes/traffic-track.test.js
+++ b/server/src/routes/traffic-track.test.js
@@ -53,6 +53,9 @@ vi.mock('../lib/logger.js', () => {
return { default: logger, logger };
});
vi.mock('../lib/traffic-visits.js', () => ({ findVisitOf: (...args) => findVisitOf(...args) }));
+// The visitor key stands in for the IP address (00250).
+const visitorKey = vi.fn();
+vi.mock('../lib/visitor-key.js', () => ({ visitorKey: (...args) => visitorKey(...args) }));
let server;
let baseUrl;
@@ -73,6 +76,8 @@ beforeEach(() => {
inserted.length = 0;
insertError = null;
findVisitOf.mockReset();
+ visitorKey.mockReset();
+ visitorKey.mockImplementation(async ({ brandId, ip }) => (ip ? `vk-${brandId}` : null));
filters.length = 0;
latestPageview = null;
updated.length = 0;
@@ -96,21 +101,35 @@ describe('POST /track/:trackingCode', () => {
findVisitOf.mockResolvedValue('p1');
const res = await beacon();
expect(res.status).toBe(204);
+ expect(visitorKey).toHaveBeenCalledWith({ brandId: 'b1', ip: '203.0.113.7' });
expect(findVisitOf).toHaveBeenCalledWith({
brandId: 'b1',
sourcePlatform: 'gemini.google.com',
- ipAddress: '203.0.113.7',
+ visitorKey: 'vk-b1',
userAgent: 'Mozilla/5.0',
});
expect(inserted[0].table).toBe('ai_traffic_logs');
expect(inserted[0].row).toMatchObject({
url: 'https://acme.example/menu',
- ip_address: '203.0.113.7',
+ visitor_key: 'vk-b1',
user_agent: 'Mozilla/5.0',
visit_of: 'p1',
});
});
+ it('never stores the IP address, and still stores the pageview when the key fails', async () => {
+ findVisitOf.mockResolvedValue(null);
+ await beacon();
+ expect(inserted[0].row).not.toHaveProperty('ip_address');
+ expect(JSON.stringify(inserted[0].row)).not.toContain('203.0.113.7');
+
+ visitorKey.mockRejectedValue(new Error('traffic_salt returned no salt'));
+ const res = await beacon();
+ expect(res.status).toBe(204);
+ expect(inserted[1].row).toMatchObject({ visitor_key: null, visit_of: null });
+ expect(findVisitOf).toHaveBeenLastCalledWith(expect.objectContaining({ visitorKey: null }));
+ });
+
it('stores a first pageview as a new visit', async () => {
findVisitOf.mockResolvedValue(null);
await beacon();
@@ -218,7 +237,7 @@ describe('POST /track/:trackingCode', () => {
expect(filters).toEqual(
expect.arrayContaining([
['eq', 'url', 'https://acme.example/menu'],
- ['eq', 'ip_address', '203.0.113.7'],
+ ['eq', 'visitor_key', 'vk-b1'],
['eq', 'user_agent', 'Mozilla/5.0'],
['eq', 'http_status', 200],
['eq', 'not_found_title', false],
diff --git a/server/src/routes/traffic.js b/server/src/routes/traffic.js
index edbbc0d92..52c86145b 100644
--- a/server/src/routes/traffic.js
+++ b/server/src/routes/traffic.js
@@ -3,6 +3,7 @@ import supabaseAdmin from '../config/supabase.js';
import { trafficLimiter } from '../middleware/rate-limiter.js';
import logger from '../lib/logger.js';
import { findVisitOf } from '../lib/traffic-visits.js';
+import { visitorKey as anonymousVisitorKey } from '../lib/visitor-key.js';
import { AI_SOURCES_VERSION, classifyAiSource } from '../lib/ai-sources.js';
import { buildTrackingScript } from '../lib/tracking-script.js';
@@ -135,12 +136,20 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)
body.nf === 1 && (httpStatus === null || (httpStatus >= 200 && httpStatus < 300));
const userAgent = (body.a || '').slice(0, 512) || null;
- const ipAddress = ip || null;
+ // The IP address itself is never stored (GDPR): only a key that tells
+ // one visitor's pageviews from another's today (visitor-key.js). If the
+ // key can't be made, the pageview is stored as a visit of its own.
+ let visitorKey = null;
+ try {
+ visitorKey = await anonymousVisitorKey({ brandId: brand.id, ip });
+ } catch (err) {
+ logger.warn({ err }, 'traffic visitor key failed; stored without one');
+ }
// The snippet's second word on a visit it just sent: a single-page app's
// title read not found only after load (00200). It marks that pageview
- // (the same address, IP and browser in the last minutes, with no status
- // or a 2xx) rather than counting another visit.
+ // (the same address, visitor and browser in the last minutes, with no
+ // status or a 2xx) rather than counting another visit.
if (body.k === 'nf') {
if (httpStatus !== null && (httpStatus < 200 || httpStatus > 299)) {
return res.status(204).end();
@@ -148,7 +157,7 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)
await markNotFoundTitle({
brandId: brand.id,
url: (body.u || '').slice(0, 2048),
- ipAddress,
+ visitorKey,
userAgent,
httpStatus,
});
@@ -160,7 +169,7 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)
// pageview is still stored, as a visit of its own.
let visitOf = null;
try {
- visitOf = await findVisitOf({ brandId: brand.id, sourcePlatform, ipAddress, userAgent });
+ visitOf = await findVisitOf({ brandId: brand.id, sourcePlatform, visitorKey, userAgent });
} catch (err) {
logger.warn({ err }, 'traffic visit lookup failed; stored as a new visit');
}
@@ -171,7 +180,7 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)
referrer: (body.r || '').slice(0, 2048) || null,
source_platform: sourcePlatform,
user_agent: userAgent,
- ip_address: ipAddress,
+ visitor_key: visitorKey,
country,
language: (body.l || '').slice(0, 16) || null,
screen: (body.d || '').slice(0, 16) || null,
@@ -197,11 +206,11 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)
const NOT_FOUND_MARK_WINDOW_MS = 10 * 60 * 1000;
/**
- * Marks the latest pageview of this address, IP and browser in the last
+ * Marks the latest pageview of this address, visitor and browser in the last
* minutes as a not-found title. Best effort: a failure is logged, the
* beacon can't be retried.
*/
-async function markNotFoundTitle({ brandId, url, ipAddress, userAgent, httpStatus }) {
+async function markNotFoundTitle({ brandId, url, visitorKey, userAgent, httpStatus }) {
try {
const since = new Date(Date.now() - NOT_FOUND_MARK_WINDOW_MS).toISOString();
let query = supabaseAdmin
@@ -211,7 +220,7 @@ async function markNotFoundTitle({ brandId, url, ipAddress, userAgent, httpStatu
.eq('url', url)
.eq('not_found_title', false)
.gte('created_at', since);
- query = ipAddress ? query.eq('ip_address', ipAddress) : query.is('ip_address', null);
+ query = visitorKey ? query.eq('visitor_key', visitorKey) : query.is('visitor_key', null);
query = userAgent ? query.eq('user_agent', userAgent) : query.is('user_agent', null);
query =
httpStatus === null ? query.is('http_status', null) : query.eq('http_status', httpStatus);
diff --git a/supabase/migrations/00250_traffic_anonymous_visitors.sql b/supabase/migrations/00250_traffic_anonymous_visitors.sql
new file mode 100644
index 000000000..b536c3950
--- /dev/null
+++ b/supabase/migrations/00250_traffic_anonymous_visitors.sql
@@ -0,0 +1,67 @@
+-- ============================================================================
+-- 00250: the tracking snippet's visitors, without their IP addresses (GDPR)
+-- ============================================================================
+-- ai_traffic_logs kept each AI-referred visitor's IP address. It was only
+-- needed to tell one visitor's pageviews from another's for half an hour
+-- (a visit, 00172) and to find the pageview a not-found title belongs to
+-- (00200).
+--
+-- The server now stores a visitor key instead (server/src/lib/visitor-key.js):
+-- a one-way hash of the IP address, the brand and a salt that changes every
+-- day. Each day's salt is made here on first use and deleted after two days,
+-- so once it is gone nothing links its keys to an address, and a visitor's
+-- days can't be joined. Visits are grouped by the key and the user agent, as
+-- they were by the IP address; a visit across midnight (UTC) counts as two.
+--
+-- The IP addresses already stored are erased. The visits they grouped are
+-- kept: each pageview's visit_of was decided when it was stored.
+
+create table if not exists public.traffic_daily_salts (
+ day date primary key,
+ salt text not null
+);
+
+comment on table public.traffic_daily_salts is
+ 'One random salt per UTC day for the tracking snippet''s visitor keys (00250). Kept two days, then deleted by traffic_salt.';
+
+alter table public.traffic_daily_salts enable row level security;
+revoke all on table public.traffic_daily_salts from anon, authenticated;
+grant all on table public.traffic_daily_salts to service_role;
+
+-- The salt of p_day, made on first use; salts older than the day before
+-- are deleted on the way.
+create or replace function public.traffic_salt(p_day date)
+returns text
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_salt text;
+begin
+ delete from public.traffic_daily_salts where day < p_day - 1;
+
+ insert into public.traffic_daily_salts (day, salt)
+ values (p_day, replace(gen_random_uuid()::text || gen_random_uuid()::text, '-', ''))
+ on conflict (day) do nothing;
+
+ select salt into v_salt from public.traffic_daily_salts where day = p_day;
+ return v_salt;
+end;
+$$;
+
+revoke all on function public.traffic_salt(date) from public, anon, authenticated;
+grant execute on function public.traffic_salt(date) to service_role;
+
+alter table public.ai_traffic_logs
+ add column if not exists visitor_key text;
+
+comment on column public.ai_traffic_logs.visitor_key is
+ 'A one-way key for the visitor, from their IP address, the brand and the day''s salt (00250); groups a visit''s pageviews. The IP address itself is not stored.';
+
+comment on column public.ai_traffic_logs.ip_address is
+ 'No longer written (00250): the IP address is not stored. Null on every row.';
+
+update public.ai_traffic_logs
+set ip_address = null
+where ip_address is not null;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index a12481483..0501e977a 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -37052,3 +37052,74 @@ revoke execute on function public.refresh_mention_terms_daily(uuid, date, date)
comment on table public.mentions_perception_snapshots is
'The Perception tab''s default view (MS-09) per brand and window (7, 30 or 90 days, every platform and region, no topic or search), as mentions_perception returns it. Written by refresh_mentions_perception_snapshot; set aside when the brand''s competitors or name change, or its Perception rollups are rebuilt (00246).';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00250_traffic_anonymous_visitors.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00250: the tracking snippet's visitors, without their IP addresses (GDPR)
+-- ============================================================================
+-- ai_traffic_logs kept each AI-referred visitor's IP address. It was only
+-- needed to tell one visitor's pageviews from another's for half an hour
+-- (a visit, 00172) and to find the pageview a not-found title belongs to
+-- (00200).
+--
+-- The server now stores a visitor key instead (server/src/lib/visitor-key.js):
+-- a one-way hash of the IP address, the brand and a salt that changes every
+-- day. Each day's salt is made here on first use and deleted after two days,
+-- so once it is gone nothing links its keys to an address, and a visitor's
+-- days can't be joined. Visits are grouped by the key and the user agent, as
+-- they were by the IP address; a visit across midnight (UTC) counts as two.
+--
+-- The IP addresses already stored are erased. The visits they grouped are
+-- kept: each pageview's visit_of was decided when it was stored.
+
+create table if not exists public.traffic_daily_salts (
+ day date primary key,
+ salt text not null
+);
+
+comment on table public.traffic_daily_salts is
+ 'One random salt per UTC day for the tracking snippet''s visitor keys (00250). Kept two days, then deleted by traffic_salt.';
+
+alter table public.traffic_daily_salts enable row level security;
+revoke all on table public.traffic_daily_salts from anon, authenticated;
+grant all on table public.traffic_daily_salts to service_role;
+
+-- The salt of p_day, made on first use; salts older than the day before
+-- are deleted on the way.
+create or replace function public.traffic_salt(p_day date)
+returns text
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_salt text;
+begin
+ delete from public.traffic_daily_salts where day < p_day - 1;
+
+ insert into public.traffic_daily_salts (day, salt)
+ values (p_day, replace(gen_random_uuid()::text || gen_random_uuid()::text, '-', ''))
+ on conflict (day) do nothing;
+
+ select salt into v_salt from public.traffic_daily_salts where day = p_day;
+ return v_salt;
+end;
+$$;
+
+revoke all on function public.traffic_salt(date) from public, anon, authenticated;
+grant execute on function public.traffic_salt(date) to service_role;
+
+alter table public.ai_traffic_logs
+ add column if not exists visitor_key text;
+
+comment on column public.ai_traffic_logs.visitor_key is
+ 'A one-way key for the visitor, from their IP address, the brand and the day''s salt (00250); groups a visit''s pageviews. The IP address itself is not stored.';
+
+comment on column public.ai_traffic_logs.ip_address is
+ 'No longer written (00250): the IP address is not stored. Null on every row.';
+
+update public.ai_traffic_logs
+set ip_address = null
+where ip_address is not null;
+