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(traffic): count ChatGPT Shopping visits from feed links tagged utm_medium=feed (#1425)
Gökhan Geyik76c87361024e
diff --git a/server/src/lib/ai-sources.js b/server/src/lib/ai-sources.jsindex 1894a7fc4..478605608 100644--- a/server/src/lib/ai-sources.js+++ b/server/src/lib/ai-sources.js@@ -15,6 +15,12 @@* up in a real property; substring matching would have booked it as AI* traffic.*+ * A source can have surfaces: a part of the assistant whose links carry+ * their own utm_medium, like ChatGPT Shopping's product cards, whose feed+ * links say utm_medium=feed (#1283). A visit through one is still the+ * source's, so the source's totals don't change; it is also marked with the+ * surface's key (ai_traffic_logs.source_surface, ga_ai_traffic_stats.surface).+ ** The list is versioned: each change adds an entry to `changes` and bumps* `version`, and every stored row records the version that counted it, so a* step in the history can be traced to the list rather than to the traffic.@@ -84,3 +90,32 @@ export function aiSourcePattern({ origin = 'analytics' } = {}) {const aliases = sources.flatMap((source) => source.aliases).map(escapeRegex);return `^((.+\\.)?(${hosts.join('|')})|(www\\.)?(${aliases.join('|')}))$`;}++/**+ * The surface of source `sourceKey` that a visit or session came through,+ * from its medium (a landing URL's utm_medium, or GA4's session medium), or+ * null for the source's ordinary links. The medium matches exactly, in any+ * case: "feed" is ChatGPT Shopping, "rss-feed" isn't.+ */+export function classifyAiSurface(sourceKey, medium) {+ const value = typeof medium === 'string' ? medium.toLowerCase() : '';+ if (!value) return null;+ const source = AI_SOURCES.find((s) => s.key === sourceKey);+ return source?.surfaces?.find((surface) => surface.medium === value)?.key ?? null;+}++/**+ * A landing URL's utm_medium: the first utm_medium parameter, its name in any+ * case, as 00251 read the URLs stored before. Empty without one, or for a+ * value that isn't a URL.+ */+export function landingMedium(url) {+ try {+ for (const [name, value] of new URL(url).searchParams) {+ if (name.toLowerCase() === 'utm_medium') return value;+ }+ } catch {+ // Not a URL: no medium.+ }+ return '';+}diff --git a/server/src/lib/ai-sources.json b/server/src/lib/ai-sources.jsonindex 9825e3bdf..b5f257a63 100644--- a/server/src/lib/ai-sources.json+++ b/server/src/lib/ai-sources.json@@ -1,5 +1,5 @@{- "version": 2,+ "version": 3,"changes": [{"version": 1,@@ -9,13 +9,19 @@"version": 2,"date": "2026-10-18","summary": "One list for both. The snippet also counts Grok, DeepSeek, OpenAI and Bard links and stores chat.openai.com as ChatGPT; Google Analytics also counts Google Labs, subdomains such as m.perplexity.ai, and its own AI Assistant channel."+ },+ {+ "version": 3,+ "date": "2026-10-23",+ "summary": "ChatGPT Shopping. A ChatGPT visit whose landing URL has utm_medium=feed, or a Google Analytics session from ChatGPT with medium feed, came through a ChatGPT Shopping product card: it is stored with the shopping surface and still counts as ChatGPT."}],"sources": [{"key": "chatgpt.com","hosts": ["chatgpt.com", "chat.openai.com"],- "aliases": ["chatgpt", "openai", "openai.com"]+ "aliases": ["chatgpt", "openai", "openai.com"],+ "surfaces": [{ "key": "shopping", "medium": "feed" }]},{ "key": "perplexity.ai", "hosts": ["perplexity.ai"], "aliases": ["perplexity"] },{ "key": "claude.ai", "hosts": ["claude.ai"], "aliases": ["claude"] },diff --git a/server/src/lib/ai-sources.test.js b/server/src/lib/ai-sources.test.jsindex 34bfff4c3..37ed02a12 100644--- a/server/src/lib/ai-sources.test.js+++ b/server/src/lib/ai-sources.test.js@@ -6,6 +6,8 @@ import {AI_SOURCE_CHANGES,aiSourcePattern,classifyAiSource,+ classifyAiSurface,+ landingMedium,} from './ai-sources.js';/**@@ -78,6 +80,40 @@ describe('aiSourcePattern', () => {});});+// #1283: a product in a merchant's feed links to its page tagged+// utm_source=chatgpt.com&utm_medium=feed.+describe('classifyAiSurface', () => {+ it("marks ChatGPT's medium feed as ChatGPT Shopping, in any case", () => {+ expect(classifyAiSurface('chatgpt.com', 'feed')).toBe('shopping');+ expect(classifyAiSurface('chatgpt.com', 'Feed')).toBe('shopping');+ });++ it("leaves ChatGPT's other mediums, and other sources' feeds, plain", () => {+ expect(classifyAiSurface('chatgpt.com', 'referral')).toBeNull();+ expect(classifyAiSurface('chatgpt.com', 'rss-feed')).toBeNull();+ expect(classifyAiSurface('chatgpt.com', '')).toBeNull();+ expect(classifyAiSurface('chatgpt.com', undefined)).toBeNull();+ expect(classifyAiSurface('perplexity.ai', 'feed')).toBeNull();+ expect(classifyAiSurface(null, 'feed')).toBeNull();+ });+});++describe('landingMedium', () => {+ it("reads a landing URL's first utm_medium, its name in any case", () => {+ expect(landingMedium('https://acme.example/p?utm_source=chatgpt.com&utm_medium=feed')).toBe(+ 'feed',+ );+ expect(landingMedium('https://acme.example/p?UTM_Medium=Feed&utm_medium=cpc')).toBe('Feed');+ });++ it('reads nothing without one, from a fragment, or from what is not a URL', () => {+ expect(landingMedium('https://acme.example/p?utm_source=chatgpt.com')).toBe('');+ expect(landingMedium('https://acme.example/p#utm_medium=feed')).toBe('');+ expect(landingMedium('/p?utm_medium=feed')).toBe('');+ expect(landingMedium(undefined)).toBe('');+ });+});+describe('the list', () => {it('has one entry per key, each naming itself', () => {const keys = AI_SOURCES.map((s) => s.key);@@ -101,4 +137,22 @@ describe('the list', () => {expect(pairs.length).toBeGreaterThan(10);for (const [, raw, key] of pairs) expect(classifyAiSource(raw), raw).toBe(key);});++ it('names the surfaces 00251 allows and marked, by a lowercase medium (#1283)', () => {+ const surfaces = AI_SOURCES.flatMap((s) =>+ (s.surfaces ?? []).map((surface) => ({ source: s.key, ...surface })),+ );+ // 00251's backfill marks ChatGPT's feed links as shopping.+ expect(surfaces).toEqual([{ source: 'chatgpt.com', key: 'shopping', medium: 'feed' }]);+ const migration = readFileSync(+ new URL('../../../supabase/migrations/00251_chatgpt_shopping_visits.sql', import.meta.url),+ 'utf8',+ );+ // Both tables' checks allow exactly the list's surfaces.+ const checks = [...migration.matchAll(/surface in \(([^)]*)\)/g)].map((m) => m[1]);+ expect(checks).toHaveLength(2);+ for (const check of checks) {+ expect(check).toBe(surfaces.map((surface) => `'${surface.key}'`).join(', '));+ }+ });});diff --git a/server/src/lib/ga-sync.js b/server/src/lib/ga-sync.jsindex ae4fbd091..a45052de8 100644--- a/server/src/lib/ga-sync.js+++ b/server/src/lib/ga-sync.js@@ -19,7 +19,7 @@import supabaseAdmin from '../config/supabase.js';import { isComposioConfigured, runGaReport } from './composio.js';-import { AI_SOURCES_VERSION } from './ai-sources.js';+import { AI_SOURCES_VERSION, classifyAiSurface } from './ai-sources.js';import {GA_AI_ASSISTANT_CHANNEL,GA_AI_SOURCE_PATTERN,@@ -164,8 +164,12 @@ const SUMMED_COLUMNS = [* The report is split by channel too, to know which sessions GA4 itself* calls AI (AT-004), so one source can come back twice for a page and day —* as a referral and as an AI Assistant session. Storage keeps one row per- * (date, source, entry URL), so those are summed into it: the same visits- * GA4 would report without the channel, never counted twice.+ * (date, source, medium, entry URL), so those are summed into it: the same+ * visits GA4 would report without the channel, never counted twice.+ *+ * The session medium is kept apart (00251): ChatGPT's sessions with medium+ * feed came through a ChatGPT Shopping product card (#1283), so the row+ * carries that surface too. It stays a ChatGPT row.*/export function mapAiTrafficRows(brandId, report) {const byKey = new Map();@@ -173,9 +177,10 @@ export function mapAiTrafficRows(brandId, report) {const date = gaDateToIso(row.date);if (!date) continue;const source = row.sessionSource ?? '';+ const medium = row.sessionMedium ?? '';const landingPageQuery = row.landingPagePlusQueryString ?? '';const metrics = trafficMetricColumns(row);- const key = `${date}|${source}|${landingPageQuery}`;+ const key = `${date}|${source}|${medium}|${landingPageQuery}`;const seen = byKey.get(key);if (seen) {for (const column of SUMMED_COLUMNS) seen[column] += metrics[column];@@ -188,6 +193,7 @@ export function mapAiTrafficRows(brandId, report) {date,source,platform: gaAiPlatform(source, row.sessionDefaultChannelGroup),+ medium,// Path for joining the page totals, full URL for attribution.landing_page: row.landingPage ?? '',landing_page_query: landingPageQuery,@@ -196,7 +202,30 @@ export function mapAiTrafficRows(brandId, report) {source_list_version: AI_SOURCES_VERSION,});}- return [...byKey.values()];+ // Once each row's platform is settled: a surface belongs to a platform.+ return [...byKey.values()].map((row) => ({+ ...row,+ surface: classifyAiSurface(row.platform, row.medium),+ }));+}++/**+ * Rows synced before the sync read the session medium (00251) have none, and+ * the medium is part of a row's key, so a re-read stores its rows beside+ * them rather than over them. Once the AI report has re-read the days from+ * `from` to `to`, their rows without a medium go: the report's replace them.+ * The daily run re-reads the last few days; the history backfill+ * (backfill-ga-ai-history.js) the rest.+ */+export async function deleteRowsWithoutMedium(brandId, { from, to }) {+ const { error } = await supabaseAdmin+ .from('ga_ai_traffic_stats')+ .delete()+ .eq('brand_id', brandId)+ .is('medium', null)+ .gte('date', from)+ .lte('date', to);+ if (error) throw new Error(`Delete from ga_ai_traffic_stats failed: ${error.message}`);}/** Landing-page totals → ga_page_stats. */@@ -414,6 +443,8 @@ async function syncBrand(brand, { aiHistory = false } = {}) {dimensions: [{ name: 'date' },{ name: 'sessionSource' },+ // ChatGPT Shopping's sessions have medium feed (#1283).+ { name: 'sessionMedium' },{ name: 'sessionDefaultChannelGroup' },{ name: 'landingPage' },{ name: 'landingPagePlusQueryString' },@@ -427,7 +458,14 @@ async function syncBrand(brand, { aiHistory = false } = {}) {});const aiMapped = mapAiTrafficRows(brand.id, aiReport);if (aiMapped.length) {- await upsertAll('ga_ai_traffic_stats', aiMapped, 'brand_id,date,source,landing_page_query');+ await upsertAll(+ 'ga_ai_traffic_stats',+ aiMapped,+ 'brand_id,date,source,medium,landing_page_query',+ );+ // Not after an empty report: that may be GA4 answering with nothing,+ // and the older rows are all those days have.+ await deleteRowsWithoutMedium(brand.id, { from: aiDays[aiDays.length - 1], to: aiDays[0] });}const aiRows = aiMapped.length;diff --git a/server/src/lib/ga-sync.test.js b/server/src/lib/ga-sync.test.jsindex 371b5f482..2c0aecce1 100644--- a/server/src/lib/ga-sync.test.js+++ b/server/src/lib/ga-sync.test.js@@ -1,8 +1,33 @@-import { describe, expect, it, vi } from 'vitest';+import { beforeEach, describe, expect, it, vi } from 'vitest';// The module imports the supabase admin client, whose config hard-exits when-// SUPABASE_* env is absent (as in CI) — stub it before the import chain.-vi.mock('../config/supabase.js', () => ({ default: {} }));+// SUPABASE_* env is absent (as in CI) — stub it before the import chain. The+// stub records deletes and their filters.+const deletes = [];+let deleteError = null;+vi.mock('../config/supabase.js', () => ({+ default: {+ from: (table) => {+ const call = { table, filters: [] };+ const filter = (op) => (col, val) => {+ call.filters.push([op, col, val]);+ return chain;+ };+ const chain = {+ delete: () => {+ deletes.push(call);+ return chain;+ },+ eq: filter('eq'),+ is: filter('is'),+ gte: filter('gte'),+ lte: filter('lte'),+ then: (resolve) => resolve({ error: deleteError }),+ };+ return chain;+ },+ },+}));import { AI_SOURCES_VERSION } from './ai-sources.js';import { GA_AI_SOURCE_PATTERN, classifyGaSource, gaAiPlatform } from './ga-sources.js';@@ -10,6 +35,7 @@ import {GA_AI_FILTER,aiReportDays,dayRange,+ deleteRowsWithoutMedium,gaDateToIso,mapAiTrafficRows,mapChannelRows,@@ -165,12 +191,13 @@ describe('readReportRows', () => {describe('mapAiTrafficRows', () => {const AI_DIMS = ['date', 'sessionSource', 'landingPage', 'landingPagePlusQueryString'];const raw = report({- dims: AI_DIMS,+ dims: ['date', 'sessionSource', 'sessionMedium', 'landingPage', 'landingPagePlusQueryString'],metrics: TRAFFIC_METRICS,rows: [['20260721','chatgpt.com',+ 'referral','/pricing','/pricing?ref=x','10',@@ -191,6 +218,9 @@ describe('mapAiTrafficRows', () => {date: '2026-07-21',source: 'chatgpt.com',platform: 'chatgpt.com',+ medium: 'referral',+ // A ChatGPT answer's link, not a ChatGPT Shopping card (#1283).+ surface: null,landing_page: '/pricing',landing_page_query: '/pricing?ref=x',sessions: 10,@@ -275,6 +305,50 @@ describe('mapAiTrafficRows', () => {expect(row.landing_page_query).toBe('/pricing?ref=x');});+ // #1283: ChatGPT Shopping's feed links are tagged utm_medium=feed.+ it("marks ChatGPT's sessions with medium feed as ChatGPT Shopping, in rows of their own", () => {+ const rows = mapAiTrafficRows(+ 'brand-1',+ report({+ dims: [+ 'date',+ 'sessionSource',+ 'sessionMedium',+ 'landingPage',+ 'landingPagePlusQueryString',+ ],+ metrics: TRAFFIC_METRICS,+ rows: [+ ['20260721', 'chatgpt.com', 'feed', '/mug', '/mug', '4', '3', '1', '4', '1', '20', '50'],+ [+ '20260721',+ 'chatgpt.com',+ 'referral',+ '/mug',+ '/mug',+ '6',+ '2',+ '0',+ '6',+ '0',+ '0',+ '40',+ ],+ ['20260721', 'chatgpt', 'Feed', '/cup', '/cup', '1', '1', '0', '1', '0', '0', '9'],+ ['20260721', 'perplexity.ai', 'feed', '/mug', '/mug', '2', '1', '0', '2', '0', '0', '8'],+ ],+ }),+ );+ expect(rows.map((r) => [r.platform, r.medium, r.surface, r.landing_page, r.sessions])).toEqual([+ // Still ChatGPT's sessions, apart from its answers' on the same page.+ ['chatgpt.com', 'feed', 'shopping', '/mug', 4],+ ['chatgpt.com', 'referral', null, '/mug', 6],+ // GA4's other name for ChatGPT, and the medium in another case.+ ['chatgpt.com', 'Feed', 'shopping', '/cup', 1],+ ['perplexity.ai', 'feed', null, '/mug', 2],+ ]);+ });+it('keeps the raw source when it cannot be classified', () => {const unknown = report({dims: AI_DIMS,@@ -323,6 +397,35 @@ describe('mapAiTrafficRows', () => {});});+describe('deleteRowsWithoutMedium', () => {+ beforeEach(() => {+ deletes.length = 0;+ deleteError = null;+ });++ it("deletes the brand's rows from before the medium was read, on the days re-read (00251)", async () => {+ await deleteRowsWithoutMedium('brand-1', { from: '2026-10-20', to: '2026-10-23' });+ expect(deletes).toEqual([+ {+ table: 'ga_ai_traffic_stats',+ filters: [+ ['eq', 'brand_id', 'brand-1'],+ ['is', 'medium', null],+ ['gte', 'date', '2026-10-20'],+ ['lte', 'date', '2026-10-23'],+ ],+ },+ ]);+ });++ it('fails the sync when the delete fails, rather than counting those days twice', async () => {+ deleteError = { message: 'permission denied' };+ await expect(+ deleteRowsWithoutMedium('brand-1', { from: '2026-10-20', to: '2026-10-23' }),+ ).rejects.toThrow('permission denied');+ });+});+describe('mapPageRows', () => {it('maps landing-page totals without a source column', () => {const raw = report({diff --git a/server/src/lib/tracking-script.js b/server/src/lib/tracking-script.jsindex 9e23c7701..95bf3e5e0 100644--- a/server/src/lib/tracking-script.js+++ b/server/src/lib/tracking-script.js@@ -8,7 +8,9 @@** It sends the source's key, not the host it saw, so chat.openai.com and* chatgpt.com are stored as one engine, and the list's version, stored with- * the visit.+ * the visit. The landing URL goes whole: the server reads a surface from its+ * utm_medium (ChatGPT Shopping's feed links, #1283), so the snippet needn't+ * know the surfaces, and a cached older copy of it counts them too.** It also sends the landing page's HTTP status as the browser saw it, for* Broken AI links (AT-012): st, from the navigation entry, or 0 where thediff --git a/server/src/lib/tracking-script.test.js b/server/src/lib/tracking-script.test.jsindex 41ab0005f..d903bb88b 100644--- a/server/src/lib/tracking-script.test.js+++ b/server/src/lib/tracking-script.test.js@@ -1,6 +1,12 @@import { runInNewContext } from 'vm';import { describe, expect, it } from 'vitest';-import { AI_SOURCES, AI_SOURCES_VERSION, classifyAiSource } from './ai-sources.js';+import {+ AI_SOURCES,+ AI_SOURCES_VERSION,+ classifyAiSource,+ classifyAiSurface,+ landingMedium,+} from './ai-sources.js';import { buildTrackingScript } from './tracking-script.js';/**@@ -118,6 +124,25 @@ describe('the tracking snippet', () => {expect(visit({ search: '?utm_source=newsletter-chatgpt-tips' })).toBeNull();});+ // #1283: a ChatGPT Shopping product card opens the product's feed link.+ it('counts a ChatGPT Shopping product card as ChatGPT, sending the URL that says so', () => {+ const search = '?utm_source=chatgpt.com&utm_medium=feed';+ for (const referrer of ['', 'https://chatgpt.com/']) {+ const beacon = visit({ referrer, search });+ expect(beacon, referrer).toMatchObject({+ s: 'chatgpt.com',+ v: AI_SOURCES_VERSION,+ u: `https://acme.example/menu${search}`,+ });+ // The server reads the surface from that URL.+ expect(classifyAiSurface(beacon.s, landingMedium(beacon.u))).toBe('shopping');+ }+ // A ChatGPT answer's link: plain ChatGPT.+ const answer = visit({ search: '?utm_source=chatgpt.com' });+ expect(answer.s).toBe('chatgpt.com');+ expect(classifyAiSurface(answer.s, landingMedium(answer.u))).toBeNull();+ });+it('counts Bing only from a Copilot answer link', () => {expect(visit({ referrer: 'https://www.bing.com/ck/a?!&&p=abc' }).s).toBe('bing.com');expect(visit({ referrer: 'https://www.bing.com/search?q=coffee' })).toBeNull();diff --git a/server/src/routes/traffic-track.test.js b/server/src/routes/traffic-track.test.jsindex 22a0b44dc..900ae371e 100644--- a/server/src/routes/traffic-track.test.js+++ b/server/src/routes/traffic-track.test.js@@ -5,7 +5,8 @@ import { AI_SOURCES_VERSION } from '../lib/ai-sources.js';/*** POST /track/:trackingCode (AT-003): each pageview is stored with the visit* it belongs to, and a failed visit lookup still stores the pageview; with- * the landing page's status, for Broken AI links (AT-012).+ * the landing page's status, for Broken AI links (AT-012), and the surface+ * it came through (ChatGPT Shopping, #1283).*/const inserted = [];@@ -175,6 +176,44 @@ describe('POST /track/:trackingCode', () => {expect(inserted.map((i) => i.row.source_list_version)).toEqual([null, null]);});+ // #1283: ChatGPT Shopping's product cards link to feed URLs tagged utm_medium=feed.+ it('stores a ChatGPT visit from a feed link as ChatGPT, surface shopping, with the list version', async () => {+ findVisitOf.mockResolvedValue(null);+ await beacon({+ u: 'https://acme.example/p/mug?utm_source=chatgpt.com&utm_medium=feed',+ r: '',+ s: 'chatgpt.com',+ v: AI_SOURCES_VERSION,+ });+ expect(inserted[0].row).toMatchObject({+ url: 'https://acme.example/p/mug?utm_source=chatgpt.com&utm_medium=feed',+ source_platform: 'chatgpt.com',+ source_surface: 'shopping',+ source_list_version: AI_SOURCES_VERSION,+ });+ // Still ChatGPT's visit: a reload continues it like any other.+ expect(findVisitOf).toHaveBeenCalledWith(+ expect.objectContaining({ sourcePlatform: 'chatgpt.com' }),+ );+ });++ it("reads the surface from the landing URL, so an older snippet's feed visits count too", async () => {+ findVisitOf.mockResolvedValue(null);+ // A cached older snippet: the host it matched, no list version.+ await beacon({ u: 'https://acme.example/p?UTM_MEDIUM=Feed', s: 'chat.openai.com' });+ // A ChatGPT answer's link.+ await beacon({ u: 'https://acme.example/p?utm_source=chatgpt.com', s: 'chatgpt.com' });+ // Another medium, or a feed link from another source.+ await beacon({ u: 'https://acme.example/p?utm_medium=email', s: 'chatgpt.com' });+ await beacon({ u: 'https://acme.example/p?utm_medium=feed', s: 'perplexity.ai' });+ expect(inserted.map((i) => [i.row.source_platform, i.row.source_surface])).toEqual([+ ['chatgpt.com', 'shopping'],+ ['chatgpt.com', null],+ ['chatgpt.com', null],+ ['perplexity.ai', null],+ ]);+ });+it('keeps a platform the list does not know as it was sent', async () => {findVisitOf.mockResolvedValue(null);await beacon({ s: 'some-new-assistant.example' });diff --git a/server/src/routes/traffic.js b/server/src/routes/traffic.jsindex 52c86145b..5b49bfc7f 100644--- a/server/src/routes/traffic.js+++ b/server/src/routes/traffic.js@@ -4,7 +4,12 @@ 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 {+ AI_SOURCES_VERSION,+ classifyAiSource,+ classifyAiSurface,+ landingMedium,+} from '../lib/ai-sources.js';import { buildTrackingScript } from '../lib/tracking-script.js';const router = Router();@@ -122,6 +127,12 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)// Stored under the AI source list's key (AT-004): an older cached t.js// still sends the host it matched, like chat.openai.com for ChatGPT.const sourcePlatform = classifyAiSource(rawPlatform) ?? rawPlatform;+ const url = (body.u || '').slice(0, 2048);+ // A visit through one of the source's surfaces, like a ChatGPT Shopping+ // product card (utm_medium=feed, #1283), read here from the landing URL+ // as stored, so a cached older snippet's visits are marked too. It stays+ // the source's visit.+ const sourceSurface = classifyAiSurface(sourcePlatform, landingMedium(url));// The list version that counted the visit; older snippets don't send one.const sourceListVersion =Number.isInteger(body.v) && body.v >= 1 && body.v <= AI_SOURCES_VERSION ? body.v : null;@@ -156,7 +167,7 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)}await markNotFoundTitle({brandId: brand.id,- url: (body.u || '').slice(0, 2048),+ url,visitorKey,userAgent,httpStatus,@@ -176,9 +187,10 @@ router.post('/track/:trackingCode', trafficLimiter, beaconBody, async (req, res)const { error: insertError } = await supabaseAdmin.from('ai_traffic_logs').insert({brand_id: brand.id,- url: (body.u || '').slice(0, 2048),+ url,referrer: (body.r || '').slice(0, 2048) || null,source_platform: sourcePlatform,+ source_surface: sourceSurface,user_agent: userAgent,visitor_key: visitorKey,country,diff --git a/server/src/scripts/backfill-ga-ai-history.js b/server/src/scripts/backfill-ga-ai-history.jsindex d0a17161b..abf60f7b0 100644--- a/server/src/scripts/backfill-ga-ai-history.js+++ b/server/src/scripts/backfill-ga-ai-history.js@@ -12,7 +12,9 @@* synced before have 90 days, counted with the old source list; this run* reads the rest and re-counts every row with the current list (version* stamped on each row). Idempotent: rows are upserted on (brand, date,- * source, entry URL), so it can be run again. It also refreshes the usual+ * source, medium, entry URL), so it can be run again. Rows synced before the+ * session medium was read (00251) are replaced, so ChatGPT Shopping's+ * sessions (#1283) show in the history too. It also refreshes the usual* last few days of page totals and products, as the daily sync does.*/diff --git a/supabase/migrations/00251_chatgpt_shopping_visits.sql b/supabase/migrations/00251_chatgpt_shopping_visits.sqlnew file mode 100644index 000000000..c2fa153d2--- /dev/null+++ b/supabase/migrations/00251_chatgpt_shopping_visits.sql@@ -0,0 +1,264 @@+-- ============================================================================+-- 00251: ChatGPT Shopping visits, from feed links tagged utm_medium=feed (#1283)+-- ============================================================================+-- A product URL in a merchant's feed tagged utm_source=chatgpt.com and+-- utm_medium=feed tells a visit from a ChatGPT Shopping product card apart+-- from one through a ChatGPT answer. Until now both were ChatGPT and nothing+-- read the medium. The AI source list (server/src/lib/ai-sources.json,+-- version 3) gives ChatGPT a shopping surface: utm_medium = feed.+--+-- * ai_traffic_logs.source_surface: 'shopping' for a snippet visit from+-- ChatGPT whose landing URL's utm_medium is feed. The server decides it+-- from the URL it stores, so a cached older snippet's visits are marked+-- too. The visit stays source_platform = 'chatgpt.com', so ChatGPT's+-- totals don't change. The rows stored before are marked below, once,+-- from their URL.+-- * ga_ai_traffic_stats.medium and surface: GA4's session medium, which+-- the sync now reads, and the surface it marks, from the list as for the+-- snippet. One source can bring sessions of several mediums to one page+-- on one day, so the medium is part of a row's key. Rows synced before+-- have none: the sync replaces them as it re-reads their days (the last+-- few each day; all of them with backfill-ga-ai-history.js).+-- * ai_traffic_merged (00176) also returns the visits by platform and+-- surface. Its platforms keep counting every visit, surfaces included.+-- * ga_platform_value (00177) also returns each platform's figures by+-- surface. Its platform rows keep counting every session, as before.+--+-- Deploy the server right after applying this: the running server's Google+-- Analytics sync upserts on the old key, which is gone, so its brands fail+-- to sync until then (the next run re-reads the last few days). The new+-- server writes source_surface, so it must not run before this.++-- ─── The snippet's visits ───────────────────────────────────────────────────++alter table public.ai_traffic_logs+ add column if not exists source_surface text+ constraint ai_traffic_logs_source_surface_check+ check (source_surface is null or source_surface in ('shopping'));++comment on column public.ai_traffic_logs.source_surface is+ 'The part of the AI source the visit came through, from the AI source list (server/src/lib/ai-sources.json): shopping for a ChatGPT Shopping product card (a ChatGPT visit whose landing URL has utm_medium=feed). Null for the source''s ordinary links. The visit still counts under source_platform (00251).';++-- Visits stored before: a ChatGPT visit whose landing URL's first+-- utm_medium parameter (its name in any case) is feed, in any case, as the+-- server reads a new visit's URL (landingMedium in ai-sources.js).+update public.ai_traffic_logs l+set source_surface = 'shopping'+where l.source_platform = 'chatgpt.com'+ and l.source_surface is null+ and l.url ilike '%utm_medium%'+ and (+ select lower(substring(p.pair from '=(.*)$'))+ from regexp_split_to_table(substring(l.url from '\?([^#]*)'), '&') with ordinality as p (pair, n)+ where lower(split_part(p.pair, '=', 1)) = 'utm_medium'+ order by p.n+ limit 1+ ) = 'feed';++-- ─── Google Analytics' sessions ─────────────────────────────────────────────++alter table public.ga_ai_traffic_stats+ add column if not exists medium text;++alter table public.ga_ai_traffic_stats+ add column if not exists surface text+ constraint ga_ai_traffic_stats_surface_check+ check (surface is null or surface in ('shopping'));++comment on column public.ga_ai_traffic_stats.medium is+ 'GA4''s session medium, as reported (feed, referral, (none), …). Part of the row''s key. Null on rows synced before the sync read it (00251), which a re-read of their day replaces.';++comment on column public.ga_ai_traffic_stats.surface is+ 'The part of the platform the sessions came through, from the AI source list (server/src/lib/ai-sources.json): shopping for ChatGPT Shopping (chatgpt.com with medium feed). Null otherwise. The sessions still count under platform (00251).';++-- The key adds the medium. A null medium is one key, not many, so the rows+-- from before stay one per (date, source, entry URL) until they're replaced.+alter table public.ga_ai_traffic_stats+ drop constraint if exists ga_ai_traffic_stats_brand_id_date_source_landing_page_query_key;++alter table public.ga_ai_traffic_stats+ drop constraint if exists ga_ai_traffic_stats_brand_date_source_medium_page_key;++alter table public.ga_ai_traffic_stats+ add constraint ga_ai_traffic_stats_brand_date_source_medium_page_key+ unique nulls not distinct (brand_id, date, source, medium, landing_page_query);++-- ─── The AI Traffic page's visits, with their surfaces ──────────────────────++create or replace function public.ai_traffic_merged(+ p_brand_id uuid,+ p_from timestamptz,+ p_to timestamptz,+ p_to_inclusive boolean default true,+ p_analytics boolean default true+)+returns jsonb+language sql+stable+security invoker+set search_path to 'public'+as $$+ with bounds as (+ select+ -- The first whole UTC day inside the window.+ case+ when p_from is null then null+ when (p_from at time zone 'utc')::time = time '00:00' then (p_from at time zone 'utc')::date+ else (p_from at time zone 'utc')::date + 1+ end as first_day,+ coalesce((p_to at time zone 'utc')::date, (now() at time zone 'utc')::date) as last_day+ ),+ snippet as (+ select+ (l.created_at at time zone 'utc')::date as day,+ coalesce(nullif(l.source_platform, ''), 'unknown') as platform,+ l.source_surface as surface,+ public.normalize_page_path(l.url) as page+ from public.ai_traffic_logs l+ where l.brand_id = p_brand_id+ and l.visit_of is null+ and l.created_at >= coalesce(p_from, '-infinity'::timestamptz)+ and (p_to is null or l.created_at < p_to or (p_to_inclusive and l.created_at = p_to))+ ),+ -- Days the snippet was active, over the whole day, not just the window.+ snippet_days as (+ select distinct (l.created_at at time zone 'utc')::date as day+ from public.ai_traffic_logs l, bounds b+ where p_analytics+ and l.brand_id = p_brand_id+ and l.visit_of is null+ and l.created_at >= coalesce((b.first_day::timestamp at time zone 'utc'), '-infinity'::timestamptz)+ and l.created_at < ((b.last_day + 1)::timestamp at time zone 'utc')+ ),+ analytics as (+ select+ g.date as day,+ coalesce(g.platform, g.source) as platform,+ g.surface,+ public.normalize_page_path(g.landing_page) as page,+ g.sessions as visits+ from public.ga_ai_traffic_stats g, bounds b+ where p_analytics+ and g.brand_id = p_brand_id+ and g.sessions > 0+ and g.date >= coalesce(b.first_day, '-infinity'::date)+ and g.date <= b.last_day+ and not exists (select 1 from snippet_days s where s.day = g.date)+ ),+ merged as (+ select day, platform, surface, page, 1::bigint as visits, 'snippet' as origin from snippet+ union all+ select day, platform, surface, page, visits::bigint, 'analytics' from analytics+ )+ select jsonb_build_object(+ 'visits', (select coalesce(sum(visits), 0) from merged),+ 'pageviews', (+ select count(*)+ from public.ai_traffic_logs l+ where l.brand_id = p_brand_id+ and l.created_at >= coalesce(p_from, '-infinity'::timestamptz)+ and (p_to is null or l.created_at < p_to or (p_to_inclusive and l.created_at = p_to))+ ),+ 'analytics_days', (+ select coalesce(jsonb_agg(distinct day order by day), '[]'::jsonb) from analytics+ ),+ 'platforms', (+ select coalesce(jsonb_agg(jsonb_build_object('platform', platform, 'visits', visits) order by visits desc, platform), '[]'::jsonb)+ from (select platform, sum(visits) as visits from merged group by platform) t+ ),+ -- Part of their platform's visits above, never added to them.+ 'surfaces', (+ select coalesce(jsonb_agg(jsonb_build_object('platform', platform, 'surface', surface, 'visits', visits) order by visits desc, platform, surface), '[]'::jsonb)+ from (+ select platform, surface, sum(visits) as visits+ from merged+ where surface is not null+ group by platform, surface+ ) t+ ),+ 'pages', (+ select coalesce(jsonb_agg(jsonb_build_object('page', page, 'visits', visits) order by visits desc, page), '[]'::jsonb)+ from (select page, sum(visits) as visits from merged group by page) t+ ),+ 'days', (+ select coalesce(jsonb_agg(jsonb_build_object('day', day, 'platform', platform, 'visits', visits) order by day, platform), '[]'::jsonb)+ from (select day, platform, sum(visits) as visits from merged group by day, platform) t+ )+ );+$$;++revoke all on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean)+ from public, anon;+grant execute on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean)+ to authenticated, service_role;++comment on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean) is+ 'AI Traffic (AT-004, spec §5.2): AI-referred visits for one brand in a window, from the tracking snippet on days it was active and from Google Analytics on other whole days, never summed. Returns visits, the snippet''s pageviews, the days Analytics filled, and visits by platform, by platform and surface (ChatGPT Shopping, 00251; part of the platform''s visits), page and day. Security invoker: RLS decides the brand.';++-- ─── Per AI platform, with its surfaces, for the Referrals by Platform table ─++-- A new column in the result: dropped and made again, with its grants.+drop function if exists public.ga_platform_value(uuid, date, date);++create function public.ga_platform_value(+ p_brand_id uuid,+ p_since date,+ p_until date+)+returns table (+ platform text,+ sessions bigint,+ engaged_sessions bigint,+ key_events bigint,+ key_event_sessions bigint,+ surfaces jsonb+)+language sql+stable+security invoker+set search_path to 'public'+as $$+ with by_surface as (+ select+ coalesce(gat.platform, gat.source) as platform,+ gat.surface,+ coalesce(sum(gat.sessions), 0)::bigint as sessions,+ coalesce(sum(gat.engaged_sessions), 0)::bigint as engaged_sessions,+ coalesce(sum(gat.key_events), 0)::bigint as key_events,+ coalesce(sum(gat.key_event_sessions), 0)::bigint as key_event_sessions+ from public.ga_ai_traffic_stats gat+ where gat.brand_id = p_brand_id+ and gat.date >= coalesce(p_since, '-infinity'::date)+ and gat.date <= p_until+ group by 1, 2+ )+ select+ s.platform,+ sum(s.sessions)::bigint,+ sum(s.engaged_sessions)::bigint,+ sum(s.key_events)::bigint,+ sum(s.key_event_sessions)::bigint,+ coalesce(+ jsonb_agg(+ jsonb_build_object(+ 'surface', s.surface,+ 'sessions', s.sessions,+ 'engaged_sessions', s.engaged_sessions,+ 'key_events', s.key_events,+ 'key_event_sessions', s.key_event_sessions+ )+ order by s.surface+ ) filter (where s.surface is not null),+ '[]'::jsonb+ )+ from by_surface s+ group by s.platform;+$$;++revoke all on function public.ga_platform_value(uuid, date, date) from public, anon;+grant execute on function public.ga_platform_value(uuid, date, date) to authenticated, service_role;++comment on function public.ga_platform_value(uuid, date, date) is+ 'AI Traffic (AT-005): Google Analytics'' sessions, engaged sessions, key events and sessions with a key event per AI platform, and the same per surface of the platform (ChatGPT Shopping, 00251; part of the platform''s figures), for one brand between two days (p_since null = from the start). Security invoker: RLS decides the brand.';++notify pgrst, 'reload schema';diff --git a/supabase/schema.sql b/supabase/schema.sqlindex 0501e977a..af173f41a 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -37123,3 +37123,271 @@ update public.ai_traffic_logsset ip_address = nullwhere ip_address is not null;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00251_chatgpt_shopping_visits.sql+-- ─────────────────────────────────────────────────────────────────────────+-- ============================================================================+-- 00251: ChatGPT Shopping visits, from feed links tagged utm_medium=feed (#1283)+-- ============================================================================+-- A product URL in a merchant's feed tagged utm_source=chatgpt.com and+-- utm_medium=feed tells a visit from a ChatGPT Shopping product card apart+-- from one through a ChatGPT answer. Until now both were ChatGPT and nothing+-- read the medium. The AI source list (server/src/lib/ai-sources.json,+-- version 3) gives ChatGPT a shopping surface: utm_medium = feed.+--+-- * ai_traffic_logs.source_surface: 'shopping' for a snippet visit from+-- ChatGPT whose landing URL's utm_medium is feed. The server decides it+-- from the URL it stores, so a cached older snippet's visits are marked+-- too. The visit stays source_platform = 'chatgpt.com', so ChatGPT's+-- totals don't change. The rows stored before are marked below, once,+-- from their URL.+-- * ga_ai_traffic_stats.medium and surface: GA4's session medium, which+-- the sync now reads, and the surface it marks, from the list as for the+-- snippet. One source can bring sessions of several mediums to one page+-- on one day, so the medium is part of a row's key. Rows synced before+-- have none: the sync replaces them as it re-reads their days (the last+-- few each day; all of them with backfill-ga-ai-history.js).+-- * ai_traffic_merged (00176) also returns the visits by platform and+-- surface. Its platforms keep counting every visit, surfaces included.+-- * ga_platform_value (00177) also returns each platform's figures by+-- surface. Its platform rows keep counting every session, as before.+--+-- Deploy the server right after applying this: the running server's Google+-- Analytics sync upserts on the old key, which is gone, so its brands fail+-- to sync until then (the next run re-reads the last few days). The new+-- server writes source_surface, so it must not run before this.++-- ─── The snippet's visits ───────────────────────────────────────────────────++alter table public.ai_traffic_logs+ add column if not exists source_surface text+ constraint ai_traffic_logs_source_surface_check+ check (source_surface is null or source_surface in ('shopping'));++comment on column public.ai_traffic_logs.source_surface is+ 'The part of the AI source the visit came through, from the AI source list (server/src/lib/ai-sources.json): shopping for a ChatGPT Shopping product card (a ChatGPT visit whose landing URL has utm_medium=feed). Null for the source''s ordinary links. The visit still counts under source_platform (00251).';++-- Visits stored before: a ChatGPT visit whose landing URL's first+-- utm_medium parameter (its name in any case) is feed, in any case, as the+-- server reads a new visit's URL (landingMedium in ai-sources.js).+update public.ai_traffic_logs l+set source_surface = 'shopping'+where l.source_platform = 'chatgpt.com'+ and l.source_surface is null+ and l.url ilike '%utm_medium%'+ and (+ select lower(substring(p.pair from '=(.*)$'))+ from regexp_split_to_table(substring(l.url from '\?([^#]*)'), '&') with ordinality as p (pair, n)+ where lower(split_part(p.pair, '=', 1)) = 'utm_medium'+ order by p.n+ limit 1+ ) = 'feed';++-- ─── Google Analytics' sessions ─────────────────────────────────────────────++alter table public.ga_ai_traffic_stats+ add column if not exists medium text;++alter table public.ga_ai_traffic_stats+ add column if not exists surface text+ constraint ga_ai_traffic_stats_surface_check+ check (surface is null or surface in ('shopping'));++comment on column public.ga_ai_traffic_stats.medium is+ 'GA4''s session medium, as reported (feed, referral, (none), …). Part of the row''s key. Null on rows synced before the sync read it (00251), which a re-read of their day replaces.';++comment on column public.ga_ai_traffic_stats.surface is+ 'The part of the platform the sessions came through, from the AI source list (server/src/lib/ai-sources.json): shopping for ChatGPT Shopping (chatgpt.com with medium feed). Null otherwise. The sessions still count under platform (00251).';++-- The key adds the medium. A null medium is one key, not many, so the rows+-- from before stay one per (date, source, entry URL) until they're replaced.+alter table public.ga_ai_traffic_stats+ drop constraint if exists ga_ai_traffic_stats_brand_id_date_source_landing_page_query_key;++alter table public.ga_ai_traffic_stats+ drop constraint if exists ga_ai_traffic_stats_brand_date_source_medium_page_key;++alter table public.ga_ai_traffic_stats+ add constraint ga_ai_traffic_stats_brand_date_source_medium_page_key+ unique nulls not distinct (brand_id, date, source, medium, landing_page_query);++-- ─── The AI Traffic page's visits, with their surfaces ──────────────────────++create or replace function public.ai_traffic_merged(+ p_brand_id uuid,+ p_from timestamptz,+ p_to timestamptz,+ p_to_inclusive boolean default true,+ p_analytics boolean default true+)+returns jsonb+language sql+stable+security invoker+set search_path to 'public'+as $$+ with bounds as (+ select+ -- The first whole UTC day inside the window.+ case+ when p_from is null then null+ when (p_from at time zone 'utc')::time = time '00:00' then (p_from at time zone 'utc')::date+ else (p_from at time zone 'utc')::date + 1+ end as first_day,+ coalesce((p_to at time zone 'utc')::date, (now() at time zone 'utc')::date) as last_day+ ),+ snippet as (+ select+ (l.created_at at time zone 'utc')::date as day,+ coalesce(nullif(l.source_platform, ''), 'unknown') as platform,+ l.source_surface as surface,+ public.normalize_page_path(l.url) as page+ from public.ai_traffic_logs l+ where l.brand_id = p_brand_id+ and l.visit_of is null+ and l.created_at >= coalesce(p_from, '-infinity'::timestamptz)+ and (p_to is null or l.created_at < p_to or (p_to_inclusive and l.created_at = p_to))+ ),+ -- Days the snippet was active, over the whole day, not just the window.+ snippet_days as (+ select distinct (l.created_at at time zone 'utc')::date as day+ from public.ai_traffic_logs l, bounds b+ where p_analytics+ and l.brand_id = p_brand_id+ and l.visit_of is null+ and l.created_at >= coalesce((b.first_day::timestamp at time zone 'utc'), '-infinity'::timestamptz)+ and l.created_at < ((b.last_day + 1)::timestamp at time zone 'utc')+ ),+ analytics as (+ select+ g.date as day,+ coalesce(g.platform, g.source) as platform,+ g.surface,+ public.normalize_page_path(g.landing_page) as page,+ g.sessions as visits+ from public.ga_ai_traffic_stats g, bounds b+ where p_analytics+ and g.brand_id = p_brand_id+ and g.sessions > 0+ and g.date >= coalesce(b.first_day, '-infinity'::date)+ and g.date <= b.last_day+ and not exists (select 1 from snippet_days s where s.day = g.date)+ ),+ merged as (+ select day, platform, surface, page, 1::bigint as visits, 'snippet' as origin from snippet+ union all+ select day, platform, surface, page, visits::bigint, 'analytics' from analytics+ )+ select jsonb_build_object(+ 'visits', (select coalesce(sum(visits), 0) from merged),+ 'pageviews', (+ select count(*)+ from public.ai_traffic_logs l+ where l.brand_id = p_brand_id+ and l.created_at >= coalesce(p_from, '-infinity'::timestamptz)+ and (p_to is null or l.created_at < p_to or (p_to_inclusive and l.created_at = p_to))+ ),+ 'analytics_days', (+ select coalesce(jsonb_agg(distinct day order by day), '[]'::jsonb) from analytics+ ),+ 'platforms', (+ select coalesce(jsonb_agg(jsonb_build_object('platform', platform, 'visits', visits) order by visits desc, platform), '[]'::jsonb)+ from (select platform, sum(visits) as visits from merged group by platform) t+ ),+ -- Part of their platform's visits above, never added to them.+ 'surfaces', (+ select coalesce(jsonb_agg(jsonb_build_object('platform', platform, 'surface', surface, 'visits', visits) order by visits desc, platform, surface), '[]'::jsonb)+ from (+ select platform, surface, sum(visits) as visits+ from merged+ where surface is not null+ group by platform, surface+ ) t+ ),+ 'pages', (+ select coalesce(jsonb_agg(jsonb_build_object('page', page, 'visits', visits) order by visits desc, page), '[]'::jsonb)+ from (select page, sum(visits) as visits from merged group by page) t+ ),+ 'days', (+ select coalesce(jsonb_agg(jsonb_build_object('day', day, 'platform', platform, 'visits', visits) order by day, platform), '[]'::jsonb)+ from (select day, platform, sum(visits) as visits from merged group by day, platform) t+ )+ );+$$;++revoke all on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean)+ from public, anon;+grant execute on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean)+ to authenticated, service_role;++comment on function public.ai_traffic_merged(uuid, timestamptz, timestamptz, boolean, boolean) is+ 'AI Traffic (AT-004, spec §5.2): AI-referred visits for one brand in a window, from the tracking snippet on days it was active and from Google Analytics on other whole days, never summed. Returns visits, the snippet''s pageviews, the days Analytics filled, and visits by platform, by platform and surface (ChatGPT Shopping, 00251; part of the platform''s visits), page and day. Security invoker: RLS decides the brand.';++-- ─── Per AI platform, with its surfaces, for the Referrals by Platform table ─++-- A new column in the result: dropped and made again, with its grants.+drop function if exists public.ga_platform_value(uuid, date, date);++create function public.ga_platform_value(+ p_brand_id uuid,+ p_since date,+ p_until date+)+returns table (+ platform text,+ sessions bigint,+ engaged_sessions bigint,+ key_events bigint,+ key_event_sessions bigint,+ surfaces jsonb+)+language sql+stable+security invoker+set search_path to 'public'+as $$+ with by_surface as (+ select+ coalesce(gat.platform, gat.source) as platform,+ gat.surface,+ coalesce(sum(gat.sessions), 0)::bigint as sessions,+ coalesce(sum(gat.engaged_sessions), 0)::bigint as engaged_sessions,+ coalesce(sum(gat.key_events), 0)::bigint as key_events,+ coalesce(sum(gat.key_event_sessions), 0)::bigint as key_event_sessions+ from public.ga_ai_traffic_stats gat+ where gat.brand_id = p_brand_id+ and gat.date >= coalesce(p_since, '-infinity'::date)+ and gat.date <= p_until+ group by 1, 2+ )+ select+ s.platform,+ sum(s.sessions)::bigint,+ sum(s.engaged_sessions)::bigint,+ sum(s.key_events)::bigint,+ sum(s.key_event_sessions)::bigint,+ coalesce(+ jsonb_agg(+ jsonb_build_object(+ 'surface', s.surface,+ 'sessions', s.sessions,+ 'engaged_sessions', s.engaged_sessions,+ 'key_events', s.key_events,+ 'key_event_sessions', s.key_event_sessions+ )+ order by s.surface+ ) filter (where s.surface is not null),+ '[]'::jsonb+ )+ from by_surface s+ group by s.platform;+$$;++revoke all on function public.ga_platform_value(uuid, date, date) from public, anon;+grant execute on function public.ga_platform_value(uuid, date, date) to authenticated, service_role;++comment on function public.ga_platform_value(uuid, date, date) is+ 'AI Traffic (AT-005): Google Analytics'' sessions, engaged sessions, key events and sessions with a key event per AI platform, and the same per surface of the platform (ChatGPT Shopping, 00251; part of the platform''s figures), for one brand between two days (p_since null = from the start). Security invoker: RLS decides the brand.';++notify pgrst, 'reload schema';+diff --git a/web/messages/en.json b/web/messages/en.jsonindex b83b9deae..89d9ed0ac 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -4649,7 +4649,11 @@"readFailed": "Couldn't read this section; export again to include it","noUncrawled": "Every cited page was read by an AI search bot in the last 30 days","uncrawledMore": "{count, plural, one {# more page not listed} other {# more pages not listed}}",- "noBrokenLinks": "No AI visitor landed on a missing page in this range"+ "noBrokenLinks": "No AI visitor landed on a missing page in this range",+ "partOfPlatform": "Part of {platform}'s visits, not added to them"+ },+ "surfaceNames": {+ "shopping": "{platform} Shopping"},"botTypes": {"training": "Training",@@ -4746,7 +4750,16 @@"engaged": "Engaged","keyEvents": "Key events","lowSample": "Low sample: {sessions, plural, one {# session} other {# sessions}} in Google Analytics",- "needsAnalytics": "Engaged and key events need Google Analytics."+ "needsAnalytics": "Engaged and key events need Google Analytics.",+ "surfaces": {+ "shopping": "Shopping"+ },+ "surfaceNames": {+ "shopping": "{platform} Shopping"+ },+ "surfaceTips": {+ "shopping": "Visits from {platform} Shopping product cards: product links in your feed tagged utm_medium=feed. They're part of {platform}'s visits, not added to them."+ }},"kpis": {"visits": "AI-referred visits",@@ -4754,6 +4767,7 @@"topPlatform": "Top platform","topPlatformTip": "The AI platform that sent the most visits in this range.","topPlatformSub": "{visits, plural, one {# visit} other {# visits}}",+ "topPlatformSurfaceSub": "{visits, plural, one {# visit} other {# visits}} · {surfaceVisits, number} from {surface}","platforms": "Platforms","platformsTip": "AI platforms that sent at least one visit in this range.","platformsSub": "unique AI sources",diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsxindex a3b01a816..6659dc1fa 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx@@ -2,8 +2,9 @@import { useRef, useState, useEffect } from 'react';import { useTranslations } from 'next-intl';-import { getPlatformName } from '@/lib/traffic-platforms';+import { getPlatformName, type PlatformSurface } from '@/lib/traffic-platforms';import { formatNumber } from '@/lib/format';+import { cn } from '@/lib/utils';import {AreaChart,Area,@@ -192,13 +193,23 @@ function PieTooltip({// ─── Bar List ─────────────────────────────────────────────────────────────────-function BarList({ data }: { data: { name: string; value: number; color: string }[] }) {+function BarList({+ data,+}: {+ /** `sub`: a surface's bar, under its platform's (ChatGPT Shopping, #1283). */+ data: { key: string; name: string; value: number; color: string; sub?: boolean; tip?: string }[];+}) {const max = Math.max(...data.map((d) => d.value), 1);return (<div className="w-full space-y-2">{data.map((item) => (- <div key={item.name} className="flex items-center gap-2 text-xs">- <span className="w-20 shrink-0 text-muted-foreground truncate">{item.name}</span>+ <div key={item.key} className="flex items-center gap-2 text-xs">+ <span+ className={cn('w-20 shrink-0 text-muted-foreground truncate', item.sub && 'pl-3')}+ title={item.tip}+ >+ {item.name}+ </span><div className="flex-1 h-1.5 rounded-full bg-muted overflow-hidden"><divclassName="h-full rounded-full transition-all"@@ -439,17 +450,46 @@ export function GoogleTrendChart({);}-export function PlatformBreakdownChart({ data }: { data: { platform: string; visits: number }[] }) {+export function PlatformBreakdownChart({+ data,+}: {+ data: {+ platform: string;+ visits: number;+ surfaces?: { surface: PlatformSurface; visits: number }[];+ }[];+}) {+ const t = useTranslations('traffic.platforms');const [hovered, setHovered] = useState<string | null>(null);const total = data.reduce((s, d) => s + d.visits, 0) || 1;+ const share = (visits: number) => Math.round((visits / total) * 100);const pieData = data.filter((d) => d.visits > 0).map((d) => ({name: getPlatformName(d.platform),- value: Math.round((d.visits / total) * 100),+ value: share(d.visits),color: getColor(d.platform),}));+ // The bars add each platform's surfaces under it. They're part of its+ // slice, so the pie leaves them out.+ const bars = data+ .filter((d) => d.visits > 0)+ .flatMap((d) => {+ const name = getPlatformName(d.platform);+ const color = getColor(d.platform);+ return [+ { key: d.platform, name, value: share(d.visits), color },+ ...(d.surfaces ?? []).map((s) => ({+ key: `${d.platform}|${s.surface}`,+ name: t(`surfaces.${s.surface}`),+ value: share(s.visits),+ color,+ sub: true,+ tip: t(`surfaceTips.${s.surface}`, { platform: name }),+ })),+ ];+ });if (!pieData.length) return null;@@ -484,7 +524,7 @@ export function PlatformBreakdownChart({ data }: { data: { platform: string; vis);}}</ChartContainer>- <BarList data={pieData} />+ <BarList data={bars} /></div>);}diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.test.tsxindex cb3e107d6..7da76a0d9 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.test.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.test.tsx@@ -69,9 +69,9 @@ const summary = (over: Partial<TrafficSummary> = {}): TrafficSummary => ({analyticsDays: [],hasPreviousPeriod: true,platformBreakdown: [- { platform: 'gemini.google.com', visits: 2, visitsPrev: 1, analytics: null },- { platform: 'chatgpt.com', visits: 1, visitsPrev: 1, analytics: null },- { platform: 'perplexity.ai', visits: 1, visitsPrev: 1, analytics: null },+ { platform: 'gemini.google.com', visits: 2, visitsPrev: 1, analytics: null, surfaces: [] },+ { platform: 'chatgpt.com', visits: 1, visitsPrev: 1, analytics: null, surfaces: [] },+ { platform: 'perplexity.ai', visits: 1, visitsPrev: 1, analytics: null, surfaces: [] },],topPages: [],hasAnyData: true,@@ -198,8 +198,8 @@ describe('TrafficKpis', () => {await render({sum: summary({platformBreakdown: [- { platform: 'made-up.example', visits: 5, visitsPrev: 0, analytics: null },- { platform: 'chatgpt.com', visits: 1, visitsPrev: 1, analytics: null },+ { platform: 'made-up.example', visits: 5, visitsPrev: 0, analytics: null, surfaces: [] },+ { platform: 'chatgpt.com', visits: 1, visitsPrev: 1, analytics: null, surfaces: [] },],}),});@@ -208,6 +208,27 @@ describe('TrafficKpis', () => {expect(card('Top platform')).not.toContain('made-up');});+ // #1283: ChatGPT Shopping's visits are part of ChatGPT's.+ it("gives the top platform's visits through a surface, without counting another platform", async () => {+ await render({+ sum: summary({+ platformBreakdown: [+ {+ platform: 'chatgpt.com',+ visits: 40,+ visitsPrev: 30,+ analytics: null,+ surfaces: [{ surface: 'shopping', visits: 11, visitsPrev: 4, analytics: null }],+ },+ { platform: 'perplexity.ai', visits: 2, visitsPrev: 1, analytics: null, surfaces: [] },+ ],+ }),+ });+ expect(card('Top platform')).toContain('ChatGPT');+ expect(card('Top platform')).toContain('40 visits · 11 from ChatGPT Shopping');+ expect(card('Platforms')).toContain('2unique AI sources');+ });+it('says how many days came from Google Analytics instead of a partial pageview count (AT-004)', async () => {await render({preset: '30d',diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.tsxindex 65aa5472b..91d5519db 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_kpis.tsx@@ -123,6 +123,7 @@ export function TrafficKpis({}) {const t = useTranslations('traffic.kpis');const tVisits = useTranslations('traffic.visits');+ const tPlatforms = useTranslations('traffic.platforms');const delta = useChangeDelta();const sourceReady = (state: TrafficSources['ga'] | undefined) =>@@ -176,6 +177,8 @@ export function TrafficKpis({const topPlatform = summary?.platformBreakdown.find((p) => p.visits > 0 && isNamedPlatform(p.platform),);+ // Its visits through a surface, most first, as the platform table lists them.+ const topSurface = topPlatform?.surfaces[0];const totals = loaded?.key === key ? loaded.totals : null;const ga = totals?.ga ?? null;const gsc = totals?.gsc ?? null;@@ -277,7 +280,20 @@ export function TrafficKpis({tooltip={t('topPlatformTip')}icon={Globe}value={topPlatform ? getPlatformName(topPlatform.platform) : '—'}- sub={topPlatform ? t('topPlatformSub', { visits: topPlatform.visits }) : t('noData')}+ sub={+ !topPlatform+ ? t('noData')+ : topSurface+ ? // Part of the platform's visits: ChatGPT Shopping (#1283).+ t('topPlatformSurfaceSub', {+ visits: topPlatform.visits,+ surfaceVisits: topSurface.visits,+ surface: tPlatforms(`surfaceNames.${topSurface.surface}`, {+ platform: getPlatformName(topPlatform.platform),+ }),+ })+ : t('topPlatformSub', { visits: topPlatform.visits })+ }/><MetricCardlabel={t('platforms')}diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_platform-breakdown.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_platform-breakdown.test.tsxnew file mode 100644index 000000000..6a376943b--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_platform-breakdown.test.tsx@@ -0,0 +1,60 @@+import { act } from 'react';+import { createRoot, type Root } from 'react-dom/client';+import { NextIntlClientProvider } from 'next-intl';+import { afterEach, beforeEach, describe, expect, it } from 'vitest';+import messages from '../../../../../../messages/en.json';+import { PlatformBreakdownChart } from './_charts';++/**+ * #1283: the Platform Breakdown card lists ChatGPT Shopping under ChatGPT,+ * as a part of ChatGPT's share rather than a platform of its own.+ */++(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =+ true;+// jsdom has no layout: the pie's container measures 0 wide and draws nothing.+globalThis.ResizeObserver ??= class {+ observe() {}+ unobserve() {}+ disconnect() {}+} as unknown as typeof ResizeObserver;++let container: HTMLDivElement;+let root: Root;++beforeEach(() => {+ container = document.createElement('div');+ document.body.appendChild(container);+ root = createRoot(container);+});++afterEach(() => {+ act(() => root.unmount());+ container.remove();+});++describe('the platform breakdown', () => {+ it("lists a platform's surface under it, as part of its share", () => {+ act(() => {+ root.render(+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">+ <PlatformBreakdownChart+ data={[+ {+ platform: 'chatgpt.com',+ visits: 30,+ surfaces: [{ surface: 'shopping', visits: 6 }],+ },+ { platform: 'claude.ai', visits: 10, surfaces: [] },+ ]}+ />+ </NextIntlClientProvider>,+ );+ });+ // Shares of all visits: ChatGPT's 75% includes its Shopping 15%.+ expect(container.textContent).toBe('ChatGPT75%Shopping15%Claude25%');+ expect(container.querySelector('[title]')?.getAttribute('title')).toContain(+ "part of ChatGPT's visits",+ );+ });+});diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_summary-line.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_summary-line.test.tsxindex abdfb002c..abd8df7cc 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_summary-line.test.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_summary-line.test.tsx@@ -44,8 +44,14 @@ const summary = (over: Partial<TrafficSummary> = {}): TrafficSummary => ({hasAnyData: true,topPages: [],platformBreakdown: [- { platform: 'chatgpt.com', visits: 38, visitsPrev: 30, analytics: ga(40, 5, 4) },- { platform: 'perplexity.ai', visits: 20, visitsPrev: 20, analytics: ga(31, 6, 5) },+ { platform: 'chatgpt.com', visits: 38, visitsPrev: 30, analytics: ga(40, 5, 4), surfaces: [] },+ {+ platform: 'perplexity.ai',+ visits: 20,+ visitsPrev: 20,+ analytics: ga(31, 6, 5),+ surfaces: [],+ },],...over,});@@ -122,8 +128,20 @@ describe('SummaryLine', () => {await render({sum: summary({platformBreakdown: [- { platform: 'chatgpt.com', visits: 38, visitsPrev: 30, analytics: ga(40, 9, 8) },- { platform: 'perplexity.ai', visits: 20, visitsPrev: 20, analytics: ga(31, 6, 5) },+ {+ platform: 'chatgpt.com',+ visits: 38,+ visitsPrev: 30,+ analytics: ga(40, 9, 8),+ surfaces: [],+ },+ {+ platform: 'perplexity.ai',+ visits: 20,+ visitsPrev: 20,+ analytics: ga(31, 6, 5),+ surfaces: [],+ },],}),});diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsxindex 8cc48aab7..68172aa21 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx@@ -2,7 +2,7 @@import { useState, useEffect, useCallback, useMemo } from 'react';import { getPlatformFilterItems } from './_charts';-import { getPlatformName } from '@/lib/traffic-platforms';+import { getPlatformName, platformTableRows } from '@/lib/traffic-platforms';import dynamic from 'next/dynamic';import { Skeleton } from '@/components/ui/skeleton';const ReferralTrendChart = dynamic(() => import('./_charts').then((m) => m.ReferralTrendChart), {@@ -856,14 +856,36 @@ function TrafficPageContent({ brand }: { brand: Brand }) {</TableRow></TableHeader><TableBody>- {(summary?.platformBreakdown ?? []).map((row) => (- <TableRow key={row.platform} className="hover:bg-muted/50">- <TableCell className="pl-6">- <span className="font-medium text-sm">- {getPlatformName(row.platform)}- </span>+ {platformTableRows(summary?.platformBreakdown ?? []).map((row) => (+ <TableRow+ key={`${row.platform}|${row.surface ?? ''}`}+ className="hover:bg-muted/50"+ >+ <TableCell className={row.surface ? 'pl-10' : 'pl-6'}>+ {row.surface ? (+ // Part of its platform's row above (#1283).+ <span+ className="text-sm text-muted-foreground"+ title={t(`platforms.surfaceTips.${row.surface}`, {+ platform: getPlatformName(row.platform),+ })}+ >+ {t(`platforms.surfaceNames.${row.surface}`, {+ platform: getPlatformName(row.platform),+ })}+ </span>+ ) : (+ <span className="font-medium text-sm">+ {getPlatformName(row.platform)}+ </span>+ )}</TableCell>- <TableCell className="text-right font-semibold tabular-nums">+ <TableCell+ className={cn(+ 'text-right tabular-nums',+ row.surface ? 'text-muted-foreground' : 'font-semibold',+ )}+ >{formatNumber(row.visits)}</TableCell><TableCell className="text-right">diff --git a/web/src/app/api/traffic/export/route.test.ts b/web/src/app/api/traffic/export/route.test.tsindex 70c4feb27..d4e59de5c 100644--- a/web/src/app/api/traffic/export/route.test.ts+++ b/web/src/app/api/traffic/export/route.test.ts@@ -67,7 +67,7 @@ beforeEach(() => {totalVisitsPrev: 1,totalPageviews: 4,hasPreviousPeriod: true,- platformBreakdown: [{ platform: 'gemini.google.com', visits: 2, visitsPrev: 1 }],+ platformBreakdown: [{ platform: 'gemini.google.com', visits: 2, visitsPrev: 1, surfaces: [] }],topPages: [{ url: '/menu', visits: 2, visitsPrev: 1 }],hasAnyData: true,});diff --git a/web/src/lib/actions/traffic-merged.test.ts b/web/src/lib/actions/traffic-merged.test.tsindex f74d31312..37216d222 100644--- a/web/src/lib/actions/traffic-merged.test.ts+++ b/web/src/lib/actions/traffic-merged.test.ts@@ -148,10 +148,11 @@ describe('getTrafficSummary', () => {visits: 116,visitsPrev: 40,analytics: { sessions: 120, engagedSessions: 80, keyEvents: 9, keyEventSessions: 7 },+ surfaces: [],},// Platforms Analytics never saw have no engagement figures.- { platform: 'perplexity.ai', visits: 47, visitsPrev: 0, analytics: null },- { platform: 'gemini.google.com', visits: 4, visitsPrev: 0, analytics: null },+ { platform: 'perplexity.ai', visits: 47, visitsPrev: 0, analytics: null, surfaces: [] },+ { platform: 'gemini.google.com', visits: 4, visitsPrev: 0, analytics: null, surfaces: [] },]);// Over the range's days, as the KPI cards read Analytics.expect(rpc).toHaveBeenCalledWith('ga_platform_value', {@@ -174,6 +175,68 @@ describe('getTrafficSummary', () => {});});+ // #1283: ChatGPT Shopping's product cards, part of ChatGPT's visits (00251).+ it("gives a platform's surfaces under it, with their own change and Analytics figures", async () => {+ rpc.mockImplementation(async (fn: string, args: { p_to_inclusive: boolean }) => {+ if (fn === 'ga_platform_value') {+ return {+ data: [+ {+ ...PLATFORM_VALUE[0],+ surfaces: [+ {+ surface: 'shopping',+ sessions: 30,+ engaged_sessions: 24,+ key_events: 5,+ key_event_sessions: 4,+ },+ ],+ },+ ],+ error: null,+ };+ }+ if (fn !== 'ai_traffic_merged') return { data: OTHER_READS[fn], error: null };+ return {+ data: args.p_to_inclusive+ ? {+ ...CURRENT,+ surfaces: [+ { platform: 'chatgpt.com', surface: 'shopping', visits: 31 },+ // A surface this page doesn't know yet stays in its platform's row.+ { platform: 'perplexity.ai', surface: 'travel', visits: 3 },+ ],+ }+ : {+ ...PREVIOUS,+ surfaces: [{ platform: 'chatgpt.com', surface: 'shopping', visits: 9 }],+ },+ error: null,+ };+ });++ const summary = await getTrafficSummary('b1', { dateFrom: '2026-10-11T12:30:00.000Z' });++ const [chatgpt, perplexity] = summary.platformBreakdown;+ // ChatGPT's own total still includes its Shopping visits.+ expect(chatgpt).toMatchObject({+ platform: 'chatgpt.com',+ visits: 116,+ analytics: { sessions: 120, engagedSessions: 80, keyEvents: 9, keyEventSessions: 7 },+ });+ expect(chatgpt.surfaces).toEqual([+ {+ surface: 'shopping',+ visits: 31,+ visitsPrev: 9,+ analytics: { sessions: 30, engagedSessions: 24, keyEvents: 5, keyEventSessions: 4 },+ },+ ]);+ expect(perplexity.surfaces).toEqual([]);+ expect(summary.totalVisits).toBe(167);+ });+it('keeps the top 10 pages for the page, and all of them for an export', async () => {const pages = Array.from({ length: 12 }, (_, i) => ({ page: `/p${i}`, visits: 12 - i }));answerMerged({ ...CURRENT, pages });diff --git a/web/src/lib/actions/traffic.ts b/web/src/lib/actions/traffic.tsindex 1756f958c..0c60dc1ea 100644--- a/web/src/lib/actions/traffic.ts+++ b/web/src/lib/actions/traffic.ts@@ -8,6 +8,7 @@ import { expandDateToEndOfDay, utcDay } from '@/lib/dates';import { isHourlyWindow, listUtcHours, utcHourKey } from '@/lib/traffic-buckets';import { CONVERSIONS_FALLBACK_DAYS, widensToLast30Days } from '@/lib/traffic-conversions';import { getSuggestionSourceStates, type SourceState } from '@/lib/actions/integrations';+import { isPlatformSurface, type PlatformSurface } from '@/lib/traffic-platforms';export interface TrafficDateWindow {dateFrom?: string;@@ -52,6 +53,12 @@ export interface TrafficSummary {visitsPrev: number;/** Google Analytics' engagement for the platform over the range's days; null without any (AT-005). */analytics: TrafficEngagement | null;+ /**+ * The visits that came through a surface of the platform, like ChatGPT+ * Shopping's product cards (#1283), most first: part of the platform's+ * visits above, never added to them.+ */+ surfaces: TrafficSurfaceVisits[];}[];topPages: {url: string;@@ -63,6 +70,15 @@ export interface TrafficSummary {hasAnyData: boolean;}+/** A platform's visits through one of its surfaces, as its row counts them. */+export interface TrafficSurfaceVisits {+ surface: PlatformSurface;+ visits: number;+ visitsPrev: number;+ /** Google Analytics' engagement for the surface's sessions; null without any. */+ analytics: TrafficEngagement | null;+}+export interface TrafficTrendPoint {/** The bucket: a UTC day ("2026-10-17"), or an hour ("2026-10-17T13:00:00.000Z") in a 24-hour window. */date: string;@@ -175,6 +191,8 @@ interface MergedTraffic {pageviews: number;analyticsDays: string[];platforms: { platform: string; visits: number }[];+ /** Part of their platform's visits (ChatGPT Shopping, #1283; 00251). */+ surfaces: { platform: string; surface: string; visits: number }[];pages: { page: string; visits: number }[];days: { day: string; platform: string; visits: number }[];}@@ -200,6 +218,7 @@ async function readMergedTraffic(pageviews?: number;analytics_days?: string[];platforms?: { platform: string; visits: number }[];+ surfaces?: { platform: string; surface: string; visits: number }[];pages?: { page: string; visits: number }[];days?: { day: string; platform: string; visits: number }[];};@@ -208,11 +227,33 @@ async function readMergedTraffic(pageviews: Number(raw.pageviews) || 0,analyticsDays: raw.analytics_days ?? [],platforms: (raw.platforms ?? []).map((p) => ({ ...p, visits: Number(p.visits) || 0 })),+ surfaces: (raw.surfaces ?? []).map((s) => ({ ...s, visits: Number(s.visits) || 0 })),pages: (raw.pages ?? []).map((p) => ({ ...p, visits: Number(p.visits) || 0 })),days: (raw.days ?? []).map((d) => ({ ...d, visits: Number(d.visits) || 0 })),};}+/** Google Analytics' figures for one surface of a platform (ga_platform_value, 00251). */+interface GaSurfaceValue {+ surface: string;+ sessions: number;+ engaged_sessions: number;+ key_events: number;+ key_event_sessions: number;+}++/** A platform's or surface's Analytics figures, as the table shows them (AT-005). */+function engagementOf(row: Omit<GaSurfaceValue, 'surface'>): TrafficEngagement {+ return {+ sessions: Number(row.sessions) || 0,+ engagedSessions: Number(row.engaged_sessions) || 0,+ keyEvents: Number(row.key_events) || 0,+ keyEventSessions: Number(row.key_event_sessions) || 0,+ };+}++const surfaceKey = (platform: string, surface: string) => `${platform}|${surface}`;+export async function getTrafficSummary(brandId: string,window?: TrafficDateWindow,@@ -264,21 +305,25 @@ export async function getTrafficSummary(if (lifetime?.[1].error) throw new Error(lifetime[1].error.message);if (value.error) throw new Error(value.error.message);const valueByPlatform = new Map(- (value.data ?? []).map((row) => [- row.platform,- {- sessions: Number(row.sessions) || 0,- engagedSessions: Number(row.engaged_sessions) || 0,- keyEvents: Number(row.key_events) || 0,- keyEventSessions: Number(row.key_event_sessions) || 0,- },- ]),+ (value.data ?? []).map((row) => [row.platform, engagementOf(row)]),+ );+ // Each platform's surfaces' figures, within the platform's (00251).+ const valueBySurface = new Map(+ (value.data ?? []).flatMap((row) =>+ ((row.surfaces ?? []) as unknown as GaSurfaceValue[]).map((s) => [+ surfaceKey(row.platform, s.surface),+ engagementOf(s),+ ]),+ ),);const hasAnyData = lifetime? lifetime[0] > 0 || (lifetime[1].data ?? []).length > 0: current.visits > 0;const previousByPlatform = new Map(previous?.platforms.map((p) => [p.platform, p.visits]));+ const previousBySurface = new Map(+ previous?.surfaces.map((s) => [surfaceKey(s.platform, s.surface), s.visits]),+ );const previousByPage = new Map(previous?.pages.map((p) => [p.page, p.visits]));return {@@ -293,6 +338,19 @@ export async function getTrafficSummary(...p,visitsPrev: previousByPlatform.get(p.platform) ?? 0,analytics: valueByPlatform.get(p.platform) ?? null,+ surfaces: current.surfaces.flatMap(({ platform, surface, visits }) =>+ // A surface this page can't name yet stays in its platform's row alone.+ platform === p.platform && visits > 0 && isPlatformSurface(surface)+ ? [+ {+ surface,+ visits,+ visitsPrev: previousBySurface.get(surfaceKey(platform, surface)) ?? 0,+ analytics: valueBySurface.get(surfaceKey(platform, surface)) ?? null,+ },+ ]+ : [],+ ),})),topPages: current.pages.slice(0, opts?.topPages ?? 10).map((p) => ({url: p.page,diff --git a/web/src/lib/traffic-export.test.ts b/web/src/lib/traffic-export.test.tsindex 209b08e08..4679f2a7b 100644--- a/web/src/lib/traffic-export.test.ts+++ b/web/src/lib/traffic-export.test.ts@@ -54,9 +54,10 @@ const data = (over: Partial<TrafficExportData> = {}): TrafficExportData => ({visits: 40,visitsPrev: 33,analytics: { sessions: 44, engagedSessions: 33, keyEvents: 6, keyEventSessions: 5 },+ surfaces: [],},- { platform: 'gemini.google.com', visits: 12, visitsPrev: 5, analytics: null },- { platform: 'claude.ai', visits: 3, visitsPrev: 0, analytics: null },+ { platform: 'gemini.google.com', visits: 12, visitsPrev: 5, analytics: null, surfaces: [] },+ { platform: 'claude.ai', visits: 3, visitsPrev: 0, analytics: null, surfaces: [] },],topPages: [{ url: '/pricing', visits: 35, visitsPrev: 30, citations: 4 }],hasAnyData: true,@@ -151,6 +152,44 @@ describe('trafficTable', () => {]);});+ // #1283+ it('lists ChatGPT Shopping under ChatGPT, saying its visits are part of ChatGPT’s', () => {+ const base = data().summary!;+ const [chatgpt, ...rest] = base.platformBreakdown;+ const summary = {+ ...base,+ platformBreakdown: [+ {+ ...chatgpt,+ surfaces: [+ {+ surface: 'shopping' as const,+ visits: 11,+ visitsPrev: 4,+ analytics: { sessions: 10, engagedSessions: 8, keyEvents: 3, keyEventSessions: 2 },+ },+ ],+ },+ ...rest,+ ],+ };+ const table = trafficTable('platforms', data({ summary }), label);+ expect(table.rows.slice(0, 2)).toEqual([+ ['ChatGPT', 40, 33, 21, 72.7, 75, 6, null],+ [+ 'ChatGPT Shopping',+ 11,+ 4,+ null,+ 20,+ 80,+ 3,+ "Part of ChatGPT's visits, not added to them; Low sample: fewer than 30 visits in this period or the one before",+ ],+ ]);+ expect(table.rows).toHaveLength(4);+ });+it("adds Google Analytics' engaged share and key events per platform, as the table does (AT-005)", () => {const table = trafficTable('platforms', data(), label);expect(table.headers).toEqual([diff --git a/web/src/lib/traffic-export.ts b/web/src/lib/traffic-export.tsindex 85842b562..0bd928b80 100644--- a/web/src/lib/traffic-export.ts+++ b/web/src/lib/traffic-export.ts@@ -22,7 +22,7 @@ import type {TrafficTrendPoint,} from '@/lib/actions/traffic';import { csvLine } from '@/lib/csv';-import { getPlatformName } from '@/lib/traffic-platforms';+import { getPlatformName, platformTableRows } from '@/lib/traffic-platforms';import { pageStatuses } from '@/lib/traffic-pages';import { conversionRate } from '@/lib/traffic-conversions';import { ctrPct, impressionsRise } from '@/lib/traffic-google-pages';@@ -198,18 +198,26 @@ function platforms(data: TrafficExportData, label: ExportLabel): ExportTable {label('columns.keyEvents'),label('columns.note'),],- rows: (s?.platformBreakdown ?? []).map((row) => {+ // A surface's row (ChatGPT Shopping, #1283) under its platform's, as the+ // table shows it, says it's part of that platform's visits: summing the+ // column would count them twice.+ rows: platformTableRows(s?.platformBreakdown ?? []).map((row) => {const delta = change(row.visits, row.visitsPrev, s!.hasPreviousPeriod, label);const ga = row.analytics;+ const platform = getPlatformName(row.platform);+ const notes = [+ row.surface ? label('notes.partOfPlatform', { platform }) : '',+ delta.note,+ ].filter(Boolean);return [- getPlatformName(row.platform),+ row.surface ? label(`surfaceNames.${row.surface}`, { platform }) : platform,row.visits,s!.hasPreviousPeriod ? row.visitsPrev : null,delta.pct,total > 0 ? Math.round((row.visits / total) * 1000) / 10 : null,ga && ga.sessions > 0 ? Math.round((ga.engagedSessions / ga.sessions) * 1000) / 10 : null,ga ? ga.keyEvents : null,- delta.note || null,+ notes.join('; ') || null,];}),};diff --git a/web/src/lib/traffic-platforms.test.ts b/web/src/lib/traffic-platforms.test.tsindex 02abf30d0..8bc1e024c 100644--- a/web/src/lib/traffic-platforms.test.ts+++ b/web/src/lib/traffic-platforms.test.ts@@ -1,7 +1,8 @@import { readFileSync } from 'node:fs';import { join } from 'node:path';import { describe, expect, it } from 'vitest';-import { getPlatformName } from './traffic-platforms';+import messages from '../../messages/en.json';+import { getPlatformName, isPlatformSurface, platformTableRows } from './traffic-platforms';import { getColor } from '@/app/[locale]/(dashboard)/dashboard/traffic/_charts';/**@@ -12,7 +13,7 @@ import { getColor } from '@/app/[locale]/(dashboard)/dashboard/traffic/_charts';const list = JSON.parse(readFileSync(join(__dirname, '../../../server/src/lib/ai-sources.json'), 'utf8'),-) as { sources: { key: string }[] };+) as { sources: { key: string; surfaces?: { key: string }[] }[] };describe('the AI source list on the page', () => {it('names every engine on the list', () => {@@ -42,4 +43,43 @@ describe('the AI source list on the page', () => {expect(getColor(key), key).not.toBe(fallback);}});++ it('names every surface on the list (#1283)', () => {+ const platforms = messages.traffic.platforms as unknown as Record<+ 'surfaces' | 'surfaceNames' | 'surfaceTips',+ Record<string, string>+ >;+ const exported = messages.traffic.export.surfaceNames as Record<string, string>;+ const surfaces = list.sources.flatMap((s) => (s.surfaces ?? []).map((surface) => surface.key));+ expect(surfaces).toContain('shopping');+ for (const key of surfaces) {+ expect(isPlatformSurface(key), key).toBe(true);+ expect(platforms.surfaces[key], key).toBeTruthy();+ expect(platforms.surfaceNames[key], key).toContain('{platform}');+ expect(platforms.surfaceTips[key], key).toBeTruthy();+ expect(exported[key], key).toBe(platforms.surfaceNames[key]);+ }+ });+});++describe('platformTableRows', () => {+ it("lists each platform's surfaces right under it, as parts of it", () => {+ const ga = { sessions: 10, engagedSessions: 8, keyEvents: 3, keyEventSessions: 2 };+ expect(+ platformTableRows([+ {+ platform: 'chatgpt.com',+ visits: 40,+ visitsPrev: 33,+ analytics: null,+ surfaces: [{ surface: 'shopping', visits: 11, visitsPrev: 4, analytics: ga }],+ },+ { platform: 'claude.ai', visits: 3, visitsPrev: 0, analytics: null, surfaces: [] },+ ]),+ ).toEqual([+ { platform: 'chatgpt.com', surface: null, visits: 40, visitsPrev: 33, analytics: null },+ { platform: 'chatgpt.com', surface: 'shopping', visits: 11, visitsPrev: 4, analytics: ga },+ { platform: 'claude.ai', surface: null, visits: 3, visitsPrev: 0, analytics: null },+ ]);+ });});diff --git a/web/src/lib/traffic-platforms.ts b/web/src/lib/traffic-platforms.tsindex 6a2b19463..7e90593d1 100644--- a/web/src/lib/traffic-platforms.ts+++ b/web/src/lib/traffic-platforms.ts@@ -1,3 +1,5 @@+import type { TrafficEngagement, TrafficSummary } from '@/lib/actions/traffic';+/*** AI referrers by the name their platform goes by. Keys are the AI source* list's (`server/src/lib/ai-sources.json`), which the tracking snippet and@@ -37,3 +39,41 @@ export function getPlatformName(platform: string): string {export function isNamedPlatform(platform: string): boolean {return platform !== 'unknown' && Object.hasOwn(PLATFORM_NAMES, platform);}++/**+ * The surfaces a platform's visits can come through, from the AI source+ * list's `surfaces`: ChatGPT Shopping's product cards (#1283). A surface's+ * visits are part of its platform's, never added to them. Each has a name+ * in en.json's traffic.platforms.surfaces.+ */+export const PLATFORM_SURFACES = ['shopping'] as const;++export type PlatformSurface = (typeof PLATFORM_SURFACES)[number];++export function isPlatformSurface(value: string): value is PlatformSurface {+ return (PLATFORM_SURFACES as readonly string[]).includes(value);+}++/** A Referrals by Platform row: a platform, or one of its surfaces. */+export interface PlatformTableRow {+ platform: string;+ /** Set on a surface's row, whose visits are part of its platform's. */+ surface: PlatformSurface | null;+ visits: number;+ visitsPrev: number;+ analytics: TrafficEngagement | null;+}++/**+ * The platforms as the table and its export list them: each platform, then+ * its surfaces right under it (ChatGPT, then ChatGPT Shopping), so a surface+ * reads as part of its platform rather than as one more.+ */+export function platformTableRows(+ breakdown: TrafficSummary['platformBreakdown'],+): PlatformTableRow[] {+ return breakdown.flatMap(({ surfaces, ...row }) => [+ { ...row, surface: null },+ ...surfaces.map((s) => ({ ...s, platform: row.platform })),+ ]);+}diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.tsindex 443d5f186..f13d8f1cb 100644--- a/web/src/types/supabase.ts+++ b/web/src/types/supabase.ts@@ -3987,6 +3987,7 @@ export type Database = {key_events: numberplatform: stringsessions: number+ surfaces: Json}[]}ga_traffic_totals: {