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.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(signals): show what AI visitors did on a traffic signal's pages (#1068)
Cihana5d3e11f08b6
diff --git a/server/src/lib/signals/library/ai-traffic-family.test.js b/server/src/lib/signals/library/ai-traffic-family.test.jsnew file mode 100644index 000000000..35fd53314--- /dev/null+++ b/server/src/lib/signals/library/ai-traffic-family.test.js@@ -0,0 +1,101 @@+import { describe, expect, it, vi } from 'vitest';++/**+ * The AI-traffic family writes, with each page, what the drawer explains it+ * with (AC-001): its sessions and, from Analytics, its AI visitors'+ * engagement and key events, beside the site's rates they were compared with.+ */++vi.mock('../../../config/supabase.js', () => ({ default: { from: vi.fn(), rpc: vi.fn() } }));+vi.mock('../../logger.js', () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));++const { LIBRARY_FAMILIES } = await import('./detect.js');++const analytics = (over) => ({+ page: '/pricing',+ cur_sessions: 40,+ prev_sessions: 42,+ cur_engaged: 30,+ cur_key_events: 8,+ prev_key_events: 5,+ ...over,+});++const run = (traffic) =>+ LIBRARY_FAMILIES.find((f) => f.name === 'aiTraffic').run({+ brandId: 'b1',+ now: new Date('2026-10-15T00:00:00Z'),+ traffic: async () => traffic,+ });++describe('the AI-traffic family', () => {+ it("records each page's engagement and key events from Analytics, and the site's", async () => {+ const found = await run({+ analytics: [+ analytics(),+ // Engaged far below the site: underperforming.+ analytics({+ page: '/guide',+ cur_sessions: 50,+ prev_sessions: 52,+ cur_engaged: 10,+ cur_key_events: 0,+ prev_key_events: 0,+ }),+ ],+ // The snippet counts visits only.+ snippet: [{ page: 'https://acme.example/blog', cur_sessions: 16, prev_sessions: 20 }],+ });+ const byKind = Object.fromEntries(found.map((f) => [f.kind, f.payload]));++ expect(byKind.ai_landing_page_winner).toEqual({+ entity: 'pages',+ targets: [+ {+ id: '/pricing',+ label: '/pricing',+ before: 42,+ now: 40,+ engagedRate: 0.75,+ keyEvents: 8,+ keyEventsBefore: 5,+ keyRate: 0.2,+ },+ ],+ siteEngagedRate: 0.444,+ siteKeyRate: 0.089,+ });+ expect(byKind.ai_landing_underperforming.targets[0]).toMatchObject({+ id: '/guide',+ engagedRate: 0.2,+ });+ expect(byKind.ai_traffic_slipping.targets).toEqual([+ { id: 'https://acme.example/blog', label: 'https://acme.example/blog', before: 20, now: 16 },+ ]);+ });++ it("counts a drop's falling pages apart from its sessions", async () => {+ const found = await run({+ analytics: [+ analytics({ page: '/a', prev_sessions: 40, cur_sessions: 10 }),+ analytics({ page: '/b', prev_sessions: 20, cur_sessions: 10 }),+ ],+ snippet: [],+ });+ const drop = found.find((f) => f.kind === 'ai_traffic_drop');+ expect(drop).toMatchObject({ previousValue: 60, currentValue: 20 });+ expect(drop.payload.pageCount).toBe(2);+ expect(drop.payload.targets.map((t) => t.id)).toEqual(['/a', '/b']);+ });++ it('records no rates without Analytics', async () => {+ const found = await run({+ analytics: [],+ snippet: [{ page: '/blog', cur_sessions: 16, prev_sessions: 20 }],+ });+ expect(found[0].payload).toEqual({+ entity: 'pages',+ targets: [{ id: '/blog', label: '/blog', before: 20, now: 16 }],+ });+ });+});diff --git a/server/src/lib/signals/library/detect.js b/server/src/lib/signals/library/detect.jsindex 1abe02e87..2ed55e612 100644--- a/server/src/lib/signals/library/detect.js+++ b/server/src/lib/signals/library/detect.js@@ -193,6 +193,34 @@ function context(brandId, now, sources) {};}+/** A rate to three places: what the drawer shows. */+const rounded = (value) => Math.round(value * 1000) / 1000;++/**+ * A page of AI traffic as the drawer shows it (AC-001): its sessions, and+ * from Analytics what its AI visitors did, the engagement and key events the+ * classification compares with the site's. The snippet counts visits only.+ */+function trafficTarget(p) {+ const target = {+ id: p.page,+ label: p.page,+ before: p.prev_sessions ?? 0,+ now: p.cur_sessions ?? 0,+ };+ if (p.source !== 'analytics') return target;+ const sessions = p.cur_sessions ?? 0;+ const share = (part) => (sessions > 0 ? rounded((part ?? 0) / sessions) : null);+ return {+ ...target,+ engagedRate: share(p.cur_engaged),+ keyEvents: p.cur_key_events ?? 0,+ keyEventsBefore: p.prev_key_events ?? 0,+ // Key events per session, as the classification compares them: can pass 1.+ keyRate: share(p.cur_key_events),+ };+}+const promptTarget = (texts) => (p) => ({id: p.prompt_id,label: String(texts.get(p.prompt_id) ?? '').slice(0, 160),@@ -574,23 +602,17 @@ const FAMILIES = [const pages = c.mergeTrafficPages(await ctx.traffic());const site = c.siteTrafficRates(pages);const source = pages.some((p) => p.source === 'analytics') ? GA : AI;+ // The site's rates the pages were compared with, from Analytics only.+ const siteRates =+ source === GA+ ? { siteEngagedRate: rounded(site.engagedRate), siteKeyRate: rounded(site.keyRate) }+ : {};const groups = {};for (const page of pages) {for (const kind of c.classifyTrafficPage(page, site, t)) (groups[kind] ??= []).push(page);}const found = Object.entries(groups).map(([kind, rows]) =>- group(- kind,- 'pages',- rows,- (p) => ({- id: p.page,- label: p.page,- before: p.prev_sessions ?? 0,- now: p.cur_sessions ?? 0,- }),- source,- ),+ group(kind, 'pages', rows, trafficTarget, source, siteRates),);if (site.prev >= t.aiTrafficMinSessions * 3 &&@@ -598,18 +620,12 @@ const FAMILIES = [) {const falling = pages.filter((p) => (p.prev_sessions ?? 0) > (p.cur_sessions ?? 0));found.push({- ...group(- 'ai_traffic_drop',- 'pages',- falling,- (p) => ({- id: p.page,- label: p.page,- before: p.prev_sessions ?? 0,- now: p.cur_sessions ?? 0,- }),- source,- ),+ // Its value is the site's sessions, so the falling pages are counted+ // apart: only the first 50 are kept as targets.+ ...group('ai_traffic_drop', 'pages', falling, trafficTarget, source, {+ ...siteRates,+ pageCount: falling.length,+ }),previousValue: site.prev,currentValue: site.cur,changeValue: site.cur - site.prev,diff --git a/web/messages/en.json b/web/messages/en.jsonindex 6cc54a9a2..26113f40a 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -350,6 +350,14 @@"viewPrompt": "View prompt","notAvailable": "Not available","none": "None",+ "trafficPages": {+ "sessions": "Sessions {before} → {now}",+ "engagement": "Engagement rate {rate}",+ "engagementVsSite": "Engagement rate {rate} (site {site})",+ "keyEvents": "Key events {before} → {now}",+ "keyRate": "{rate} key events per session",+ "keyRateVsSite": "{rate} key events per session (site {site})"+ },"referrals": {"none": "No AI referrals","period": "Visits in the last {days} days, against the {days} before"diff --git a/web/src/components/action-center/signal-detail-blocks.test.tsx b/web/src/components/action-center/signal-detail-blocks.test.tsxindex 9f684e58f..48321d3a5 100644--- a/web/src/components/action-center/signal-detail-blocks.test.tsx+++ b/web/src/components/action-center/signal-detail-blocks.test.tsx@@ -459,6 +459,79 @@ describe('a traffic signal with its referrals and prompts', () => {});});+describe("an AI-traffic finding's pages", () => {+ const rowsOf = () =>+ [...container.querySelectorAll('dt')].map(+ (dt) => `${dt.textContent}: ${dt.nextElementSibling?.textContent}`,+ );+ const page = {+ id: '/guide',+ label: '/guide',+ before: 52,+ now: 50,+ engagedRate: 0.2,+ keyEvents: 1,+ keyEventsBefore: 3,+ keyRate: 0.02,+ };++ it('says how engaged its AI visitors were against the site', () => {+ render(+ <SignalWhereBlock+ signal={signal({+ category: 'traffic',+ kind: 'ai_landing_underperforming',+ currentValue: 1,+ payload: { entity: 'pages', targets: [page], siteEngagedRate: 0.444, siteKeyRate: 0.089 },+ where: NO_WHERE,+ })}+ />,+ );+ expect(rowsOf()).toContain('Pages: /guideSessions 52 → 50 · Engagement rate 20% (site 44%)');+ });++ it("counts a winning page's key events per session, which can pass one", () => {+ render(+ <SignalWhereBlock+ signal={signal({+ category: 'traffic',+ kind: 'ai_landing_page_winner',+ currentValue: 1,+ payload: {+ entity: 'pages',+ targets: [{ ...page, keyEvents: 75, keyEventsBefore: 40, keyRate: 1.5 }],+ siteKeyRate: 0.089,+ },+ where: NO_WHERE,+ })}+ />,+ );+ expect(rowsOf()).toContain(+ 'Pages: /guideSessions 52 → 50 · Key events 40 → 75 · 1.5 key events per session (site 0.09)',+ );+ });++ it('gives the key events a converting page lost, and only sessions without Analytics', () => {+ render(+ <SignalWhereBlock+ signal={signal({+ category: 'traffic',+ kind: 'converting_page_slipping',+ currentValue: 2,+ payload: {+ entity: 'pages',+ targets: [page, { id: '/blog', label: '/blog', before: 20, now: 16 }],+ },+ where: NO_WHERE,+ })}+ />,+ );+ expect(rowsOf()).toContain(+ 'Pages: /guideSessions 52 → 50 · Key events 3 → 1/blogSessions 20 → 16',+ );+ });+});+describe('SignalEvidenceBlock', () => {it('links the answers and the action the signal is used by', async () => {getSignalActions.mockResolvedValue([diff --git a/web/src/components/action-center/signal-detail-blocks.tsx b/web/src/components/action-center/signal-detail-blocks.tsxindex 26f7c9c70..c8c87321a 100644--- a/web/src/components/action-center/signal-detail-blocks.tsx+++ b/web/src/components/action-center/signal-detail-blocks.tsx@@ -211,6 +211,69 @@ function WhereValueView({ value }: { value: WhereValue }) {);case 'crawlers':return <span>{value.agents.map(crawlerName).join(', ')}</span>;+ case 'trafficPages': {+ const shown = value.items.slice(0, LIST_LIMIT);+ // Engagement is a share of sessions; key events are counted per+ // session, which can pass one.+ const percent = (share: number) =>+ format.number(share, { style: 'percent', maximumFractionDigits: 0 });+ const perSession = (rate: number) => format.number(rate, { maximumFractionDigits: 2 });+ const versus = (+ key: 'engagement' | 'keyRate',+ value: number,+ site: number | null,+ shown: (n: number) => string,+ ) =>+ site === null+ ? t(`drawer.trafficPages.${key}`, { rate: shown(value) })+ : t(`drawer.trafficPages.${key}VsSite`, { rate: shown(value), site: shown(site) });+ return (+ <ul className="space-y-2">+ {shown.map((item) => {+ // The sessions, then what the finding was raised on.+ const facts: string[] = [];+ if (item.sessions !== null && item.before !== null) {+ facts.push(+ t('drawer.trafficPages.sessions', {+ before: format.number(item.before),+ now: format.number(item.sessions),+ }),+ );+ }+ for (const metric of value.metrics) {+ if (metric === 'engagement' && item.engagedRate !== null) {+ facts.push(versus('engagement', item.engagedRate, value.siteEngagedRate, percent));+ }+ if (metric === 'keyRate' && item.keyRate !== null) {+ facts.push(versus('keyRate', item.keyRate, value.siteKeyRate, perSession));+ }+ if (metric === 'keyEvents' && item.keyEvents !== null) {+ facts.push(+ t('drawer.trafficPages.keyEvents', {+ before: format.number(item.keyEventsBefore ?? 0),+ now: format.number(item.keyEvents),+ }),+ );+ }+ }+ return (+ <li key={item.page}>+ <span className="block break-all">{item.page}</span>+ <span className="block text-xs text-muted-foreground">+ {facts.map((fact, i) => (+ <span key={i}>+ {i > 0 && ' · '}+ <span className="whitespace-nowrap">{fact}</span>+ </span>+ ))}+ </span>+ </li>+ );+ })}+ <More shown={shown.length} total={value.total} />+ </ul>+ );+ }case 'referrals': {const shown = value.items.slice(0, LIST_LIMIT);return (diff --git a/web/src/lib/signals/detail.test.ts b/web/src/lib/signals/detail.test.tsindex a5776445d..50769b028 100644--- a/web/src/lib/signals/detail.test.ts+++ b/web/src/lib/signals/detail.test.ts@@ -607,3 +607,114 @@ describe('the AI-traffic windows', () => {expect(signalWhereFields(site).map((f) => f.key)).toEqual(['scope', 'aiReferrals']);});});++describe("an AI-traffic finding's pages", () => {+ const winner = signal({+ category: 'traffic',+ kind: 'ai_landing_page_winner',+ payload: {+ entity: 'pages',+ targets: [+ {+ id: '/pricing',+ label: '/pricing',+ before: 42,+ now: 40,+ engagedRate: 0.75,+ keyEvents: 8,+ keyEventsBefore: 5,+ keyRate: 0.2,+ },+ ],+ siteEngagedRate: 0.444,+ siteKeyRate: 0.089,+ },+ currentValue: 1,+ });++ it('gives each page its sessions and what its AI visitors did, beside the site', () => {+ const pages = signalWhereFields(winner).find((f) => f.key === 'pages')?.value;+ expect(pages).toEqual({+ type: 'trafficPages',+ items: [+ {+ page: '/pricing',+ sessions: 40,+ before: 42,+ engagedRate: 0.75,+ keyRate: 0.2,+ keyEvents: 8,+ keyEventsBefore: 5,+ },+ ],+ total: 1,+ metrics: ['keyEvents', 'keyRate'],+ siteEngagedRate: 0.444,+ siteKeyRate: 0.089,+ });+ // `items` stays the page list other signals give; the figures ride beside.+ expect(signalDetailForApi(winner, []).where.pages).toEqual({+ total: 1,+ items: ['/pricing'],+ traffic: [+ {+ page: '/pricing',+ sessions: 40,+ sessions_before: 42,+ engaged_rate: 0.75,+ key_events: 8,+ key_events_before: 5,+ key_events_per_session: 0.2,+ },+ ],+ site_engaged_rate: 0.444,+ site_key_events_per_session: 0.089,+ });+ });++ it("counts a drop's pages, not its sessions, and reads a snippet page's visits only", () => {+ const drop = signal({+ category: 'traffic',+ kind: 'ai_traffic_drop',+ payload: {+ entity: 'pages',+ targets: [{ id: '/blog', label: '/blog', before: 20, now: 6 }],+ pageCount: 120,+ },+ previousValue: 120,+ currentValue: 70,+ });+ expect(signalWhereFields(drop).find((f) => f.key === 'pages')?.value).toEqual({+ type: 'trafficPages',+ items: [+ {+ page: '/blog',+ sessions: 6,+ before: 20,+ engagedRate: null,+ keyRate: null,+ keyEvents: null,+ keyEventsBefore: null,+ },+ ],+ total: 120,+ metrics: [],+ siteEngagedRate: null,+ siteKeyRate: null,+ });+ });++ it('leaves out sessions a target does not record', () => {+ const bare = signal({+ category: 'traffic',+ kind: 'ai_traffic_slipping',+ payload: { entity: 'pages', targets: [{ id: '/blog', label: '/blog' }] },+ currentValue: 1,+ });+ const pages = signalWhereFields(bare).find((f) => f.key === 'pages')?.value;+ expect(pages?.type === 'trafficPages' && pages.items[0]).toMatchObject({+ sessions: null,+ before: null,+ });+ });+});diff --git a/web/src/lib/signals/detail.ts b/web/src/lib/signals/detail.tsindex 1609f0138..56297e734 100644--- a/web/src/lib/signals/detail.ts+++ b/web/src/lib/signals/detail.ts@@ -402,6 +402,18 @@ export type WhereValue =| { type: 'issues'; items: PageIssue[] }/** AI crawlers by robots.txt user agent (`gptbot`). */| { type: 'crawlers'; agents: string[] }+ /**+ * AI-traffic pages: their sessions and, from Analytics, what their AI+ * visitors did; `metrics` are those the signal's kind is about.+ */+ | {+ type: 'trafficPages';+ items: TrafficPage[];+ total: number;+ metrics: TrafficMetric[];+ siteEngagedRate: number | null;+ siteKeyRate: number | null;+ }/** AI visits by platform, per page or for the site, over two windows of `days`. */| { type: 'referrals'; items: PageReferrals[]; days: number }| { type: 'locations'; codes: readonly string[] }@@ -523,6 +535,42 @@ function blockedCrawlers(issues: PageIssue[]): string[] {return [...new Set(agents)];}+/** A page's AI sessions, and from Analytics what its AI visitors did. */+export interface TrafficPage {+ page: string;+ /** AI sessions now and in the window before; null when not recorded. */+ sessions: number | null;+ before: number | null;+ /** Engaged sessions' share, 0–1; null without Analytics. */+ engagedRate: number | null;+ /** Key events per session (can pass 1); null without Analytics. */+ keyRate: number | null;+ keyEvents: number | null;+ keyEventsBefore: number | null;+}++export type TrafficMetric = 'engagement' | 'keyEvents' | 'keyRate';++// What each AI-traffic finding was raised on, beside the sessions+// (server signals/library/classify.js classifyTrafficPage).+const TRAFFIC_METRICS: Record<string, TrafficMetric[]> = {+ ai_landing_underperforming: ['engagement'],+ ai_landing_page_winner: ['keyEvents', 'keyRate'],+ converting_page_slipping: ['keyEvents'],+};++function trafficPages(targets: Target[]): TrafficPage[] {+ return targets.map((t) => ({+ page: label(t),+ sessions: num(t.now),+ before: num(t.before),+ engagedRate: num(t.engagedRate),+ keyRate: num(t.keyRate),+ keyEvents: num(t.keyEvents),+ keyEventsBefore: num(t.keyEventsBefore),+ }));+}+/** A page's AI visits (the site's, with no page) by referring platform. */export interface PageReferrals {page: string | null;@@ -691,6 +739,12 @@ interface Target {checks?: unknown;issues?: unknown;page?: unknown;+ before?: unknown;+ now?: unknown;+ engagedRate?: unknown;+ keyRate?: unknown;+ keyEvents?: unknown;+ keyEventsBefore?: unknown;}function targetsOf(signal: Signal): Target[] {@@ -805,6 +859,20 @@ function fieldValue(signal: Signal, key: WhereFieldKey): WhereValue | null {return url ? { type: 'text', text: url } : null;}case 'pages': {+ if (AI_TRAFFIC_KINDS.has(signal.kind) && targets.length && !isSiteWide(signal)) {+ return {+ type: 'trafficPages',+ items: trafficPages(targets),+ // A drop's value is the site's sessions; its pages are counted apart.+ total:+ signal.kind === 'ai_traffic_drop'+ ? Math.max(targets.length, num(p.pageCount) ?? 0)+ : total,+ metrics: TRAFFIC_METRICS[signal.kind] ?? [],+ siteEngagedRate: num(p.siteEngagedRate),+ siteKeyRate: num(p.siteKeyRate),+ };+ }if (entity === 'pages' && targets.length && targets[0]?.id !== 'site') {return { type: 'list', items: targets.map(label), total };}@@ -1055,6 +1123,23 @@ function apiValue(value: WhereValue): unknown {}));case 'crawlers':return value.agents;+ case 'trafficPages':+ // `items` stays the page list every other signal's `pages` gives.+ return {+ total: value.total,+ items: value.items.map((item) => item.page),+ traffic: value.items.map((item) => ({+ page: item.page,+ sessions: item.sessions,+ sessions_before: item.before,+ engaged_rate: item.engagedRate,+ key_events: item.keyEvents,+ key_events_before: item.keyEventsBefore,+ key_events_per_session: item.keyRate,+ })),+ site_engaged_rate: value.siteEngagedRate,+ site_key_events_per_session: value.siteKeyRate,+ };case 'referrals':return {days: value.days,