Wie Sie Ihre Marke in der AI-Suche verfolgen können

Traditionelles SEO-Reporting war früher einfach: Sie verfolgten Rankings, überprüften Impressionen und Klicks in Search Console und ordneten diese Zahlen den geschäftlichen Auswirkungen zu. Die KI-gesteuerte Suche hat diesen Ablauf umgestaltet. Plattformen wie Google AI Overviews, AI Mode, Perplexity und Bing Copilot listen nicht mehr nur Ergebnisse auf - sie generieren Antworten und wählen aus, auf welche Quellen sie verweisen. Diese Verschiebung bedeutet, dass die Schlüsselfrage nicht mehr lautet: "Werden wir gerankt?", sondern "Werden wir in der generativen Ebene zitiert?"

Die Herausforderung besteht darin, dass diese Antwortebene nicht sauber in die vorhandenen Analysetools passt und nicht stabil ist. Eine Suchanfrage, die heute Ihre Marke zitiert, schließt Sie morgen möglicherweise nicht mehr ein, selbst wenn sich an Ihrer Website nichts geändert hat. Bei der GEO-Analyse geht es darum, diese verborgene Ebene zu beleuchten, zu verfolgen, wie sie sich bewegt, und diese Erscheinungen mit messbaren Ergebnissen zu verbinden.

Aktive und passive Methoden zur Erkennung von Sichtbarkeit

Eine zuverlässige GEO-Messung kombiniert zwei Ansätze: aktive Überprüfung, wo Sie auftauchen, und passive Beobachtung, wie Suchsysteme mit Ihrer Website interagieren.

Aktive Erkennung bedeutet, dass Sie Ihre eigenen Überwachungsagenten erstellen, die KI-Suchmaschinen abfragen, die Antworten erfassen und nach Erwähnungen Ihrer Domäne suchen. Dabei kann es sich um ein einfaches Skript zur Browser-Automatisierung handeln, das eine Reihe von Abfragen ausführt und Screenshots speichert, oder um eine vollständige Pipeline, die strukturierte Zitationsdaten aus HTML- oder JSON-Ausgaben speichert. Das Wichtigste ist die Wiederholung - die KI-Antworten werden jedes Mal neu generiert, sodass Sie diese Agenten häufig ausführen müssen, um zu erfassen, wie sich die Ergebnisse verändern. Diese Schwankungen sind an sich schon nützliche Daten, vor allem, wenn Sie sie mit Änderungen in Ihren eigenen Inhalten oder im breiteren Wettbewerbsumfeld vergleichen.

Die passive Erkennung erfolgt über Ihre Serverprotokolle. Indem Sie die Anfragen von KI-Crawlern verfolgen, können Sie sehen, wann diese Systeme Ihre Seiten abrufen. Wenn Sie z. B. feststellen, dass PerplexityBot bestimmte URLs häufiger aufruft und dann einen Anstieg der Zitate für dieselben Seiten feststellt, haben Sie einen klaren Zusammenhang zwischen Abruf und Exposition aufgedeckt. Mit einer erweiterten Analyse können Sie diese Bot-Besuche nach Seiten gruppieren und herausfinden, welche Teile Ihrer Website vorrangig behandelt werden.

Verfolgung von AI-Suchbots

Einer der direktesten Wege, um zu verstehen, wie Ihr Inhalt in generative Antworten einfließt, ist die genaue Beobachtung der Bots, die Ihre Website crawlen. Diese User Agents stellen die Abrufebene für Plattformen wie ChatGPT, Claude, Perplexity, Bing Copilot und andere dar. Indem Sie sie in Ihren Serverprotokollen überwachen, erhalten Sie ein frühes Signal dafür, wann und wie Ihre Inhalte für die potenzielle Aufnahme in KI-generierte Antworten gesammelt werden.

Diese Sichtbarkeit ist wichtig, da Änderungen in der Crawling-Aktivität oft mit Verschiebungen in Ihrer Präsenz in den KI-Suchfunktionen übereinstimmen. Wenn bestimmte Bots ihre Besuche erhöhen, kann dies ein Hinweis darauf sein, dass Ihre Seiten mit größerer Wahrscheinlichkeit abgerufen und zitiert werden. Die Erstellung und Pflege einer aktuellen Liste dieser Crawler und der anschließende Abgleich ihrer Aktivitäten mit Ihrer generativen Sichtbarkeit bietet Ihnen eine der wenigen greifbaren Möglichkeiten, einen Prozess zu messen, der ansonsten im Dunkeln stattfindet.

Anbieter	Benutzeragent / Token	Zweck	Wie man verwaltet	Zusätzliche Anmerkungen
OpenAI	GPTBot	Sammelt Inhalte für das Training des OpenAI-Modells	Blockieren oder zulassen in robots.txt (Benutzer-Agent: GPTBot)	Dokumentiert auf der offiziellen Website von OpenAI
	OAI-SearchBot	Holt Seiten für ChatGPTs Suchergebnisse, nicht für das Training	Benutzer-Agent: OAI-SearchBot	Speziell für den Abruf verwendet
Anthropisch	ClaudeBot	Breit angelegter Crawler für Claude-Modell-Training	Kontrolle mit robots.txt	Öffentlich erklärt in der Anthropic-Hilfe
	Claude-Benutzer	Fetcher ausgelöst bei Live-Benutzerabfragen	Benutzer-Agent: Claude-Benutzer	Unterscheidet sich vom Trainingsbot
Perplexität	PerplexityBot	Haupt-Crawler, der den Index von Perplexity aufbaut	Benutzer-Agent: PerplexityBot	Veröffentlichen von IP-Bereichen und Bot-Details
	Perplexity-Benutzer	Abruf von Anfragen, wenn ein Benutzer eine Frage stellt	Benutzer-Agent: Perplexity-User	Nicht für die langfristige Indexierung verwendet
Google	Googlebot-Familie	Standard-Crawler für Web, Bilder, Video usw.	Kontrolliert in robots.txt	Füttert sowohl Such- als auch generative Funktionen
	Google-Extended	Token, das die Verwendung Ihrer Inhalte in KI-Funktionen regelt	In robots.txt als User-Agent hinzufügen: Google-Extended	Kein Crawler selbst, sondern nur ein Steuerschalter
Microsoft	bingbot	Der primäre Crawler von Bing, der auch für Copilot verwendet wird	Benutzer-Agent: bingbot	Verhält sich wie Googlebot mit AI-Integration
Apfel	Applebot	Crawler für Siri, Spotlight und Apple-Dienste	Benutzer-Agent: Applebot	Standard-Apple-Crawler
	Applebot-Erweiterung	Token für den Ausstieg aus der Nutzung von Apples KI-Training	Kontrolle in robots.txt	Betrifft nur das Modelltraining, nicht das Crawling

Mit NUOPTIMA die Sichtbarkeit gestalten

Unter NUOPTIMAUnter Sichtbarkeit verstehen wir mehr als Suchergebnisse. Bei KI-gesteuerten Ergebnissen geht es darum, ob Ihre Marke in der Antwort selbst erkannt, zitiert und als vertrauenswürdig eingestuft wird. Deshalb verbinden wir klassische SEO mit generativer Suchmaschinenoptimierung und helfen Marken, dort präsent zu sein, wo es am wichtigsten ist.

Wir kombinieren Strategie, Daten und Umsetzung, um sicherzustellen, dass Ihre Inhalte sowohl von KI-Systemen abgerufen werden können als auch für reale Nutzer von Nutzen sind. Unsere Arbeit umfasst technische SEO, internationale Optimierung und Inhalte, die messbares Wachstum fördern. Das Ergebnis ist eine bessere Sichtbarkeit, die sich direkt in Geschäftsergebnissen niederschlägt.

Warum Marken uns wählen:

• Nachgewiesene Ergebnisse mit mehr als 70 Branchenführern in verschiedenen Sektoren
• 3-fache durchschnittliche Rendite der Werbeausgaben für organische und bezahlte Kampagnen
• Erfahrung in der Skalierung von SaaS, eCommerce, Gesundheitswesen und mehr
• Ein Gleichgewicht zwischen KI-gesteuerten Erkenntnissen und menschengesteuerter Strategie

Bei unserem Ansatz geht es nicht darum, eitle Metriken zu verfolgen. Es geht darum, Sichtbarkeit zu schaffen, die bleibt - Präsenz in KI-Antworten, Glaubwürdigkeit bei Nutzern und dauerhafte Gewinne bei Traffic und Umsatz. Indem wir uns darauf konzentrieren, wie KI-Systeme Informationen abrufen und zitieren, helfen wir Marken, sich eine Position in den Gesprächen zu sichern, die die Entscheidungen beeinflussen.

Wir wissen auch, dass jedes Unternehmen anders ist. Deshalb stimmen wir unsere Strategien auf Ihre Branche, Ihre Zielgruppe und Ihre Wachstumsziele ab. Ganz gleich, ob Sie ein Startup-Unternehmen sind, das auf der Suche nach Bodenhaftung ist, oder ein etabliertes Unternehmen, das weltweit skaliert - wir wenden dieselbe datengestützte Denkweise an, um messbare Ergebnisse zu erzielen.

Letztendlich ist unsere Mission einfach: Wir sorgen dafür, dass Ihre Marke nicht nur in der Suche erscheint, sondern dass sie in der KI-gestützten Zukunft der Entdeckung hervorsticht.

Erkennung von AI-Übersichten und AI-Modus

Google betreibt sowohl AI Overviews als auch AI Mode auf seinen generativen Systemen, aber die beiden verhalten sich unterschiedlich, was bedeutet, dass man sie auf unterschiedliche Weise messen muss.

AI Übersichten

Übersichten erscheinen direkt auf der Seite mit den Suchergebnissen, in der Regel dann, wenn Google entscheidet, dass eine schnelle, zusammengefasste Zusammenfassung das Erlebnis verbessert. Um sie zu erkennen, reicht es nicht aus, einen Blick auf die Rankings zu werfen. Sie müssen die gesamte SERP erfassen, nach dem Übersichtsblock suchen und prüfen, ob in der Antwort auf Ihre Website verwiesen wird oder diese als Quelle verlinkt ist.

Das Problem ist, dass die Übersichten nicht fix sind. Eine Abfrage kann am Morgen ein Ergebnis und am Nachmittag ein völlig anderes Ergebnis liefern. Manchmal verschwindet der Block sogar ganz. Diese Instabilität macht eine kontinuierliche Verfolgung unabdingbar - ein einziger Screenshot sagt fast nichts aus, aber wiederholte Überprüfungen offenbaren das wahre Muster Ihrer Präsenz.

AI-Modus

Der KI-Modus funktioniert anders. Er befindet sich in einer eigenen Registerkarte und produziert längere, dialogische Antworten. Da er darauf abzielt, einen Dialog aufrechtzuerhalten, weichen die Quellen, die er zitiert, oft von denen ab, die in den Übersichten angezeigt werden. Die Messung der Sichtbarkeit bedeutet hier, dass die gesamte Konversationsausgabe erfasst und jeder enthaltene Link extrahiert wird.

Durch den Vergleich der beiden: Übersichten und KI-Modus - können Sie sehen, wie Google je nach Kontext unterschiedliche Websites bevorzugt. Diese Seite-an-Seite-Ansicht deckt oft Verzerrungen der Plattformen auf und zeigt, wo Ihre Marke in der einen Umgebung stark ist, aber in der anderen fehlt.

Verfolgung von AI-Übersichten und AI-Modus mit FetchSERP

Eine der einfachsten Möglichkeiten, Ihre Sichtbarkeit in den KI-Oberflächen von Google zu überwachen, ist FetchSERP. Die Plattform bietet eine Reihe von API-Endpunkten, die sowohl traditionelle SERP-Daten als auch generative Ergebnisse zurückgeben können. Für das GEO-Tracking sind die beiden Endpunkte am wichtigsten:

• /serp_ai - kombiniert die KI-Übersicht und den KI-Modus in einer Nutzlast, wenn sie verfügbar sind.
• /serp_ai_mode - ein schnellerer, auf die USA beschränkter Endpunkt, der sich speziell auf die Ergebnisse des AI-Modus konzentriert.

Für beide ist ein API-Token in der Kopfzeile erforderlich, und jede Anfrage benötigt Ihre Suchanfrage sowie einen optionalen Länderparameter (Standard ist USA).

Wie es sich in Blätter einfügt

Um alles zu organisieren, sollten Sie diese API-Aufrufe mit einem Google Sheet verbinden. Die folgende Struktur ist am besten geeignet:

• Schlüsselwörter: Ihre Abfrageliste (Spalte A sollte "Stichwort" lauten, gefolgt von einer Abfrage pro Zeile).
• AIO_Ergebnisse: Automatisch mit Flaggen und Quellenangaben versehen, wenn eine KI-Übersicht Ihre Marke zeigt.
• AI_Modus_Ergebnisse: Ähnliche Ausgabe für Abfragen im AI-Modus.
• GEO_AISummary: Eine laufende Zusammenfassung mit Diagrammen, die zeigen, wie viele Abfragen jede KI-Oberfläche ausgelöst hat.

Jedes Mal, wenn das Skript ausgeführt wird, fügt es neuen Zeilen einen Zeitstempel hinzu. So können Sie ein historisches Protokoll erstellen, das nicht nur zeigt, ob Sie zitiert werden, sondern auch, wie sich diese Sichtbarkeit im Laufe der Zeit verändert.

Warum das wichtig ist

Wenn Sie das Skript mehrmals am Tag ausführen, können Sie kurzfristige Schwankungen erfassen, während tägliche Durchläufe eine zuverlässige Langzeitbetrachtung ermöglichen. Mit der Zeit können Sie:

• Häufigkeit und Konsistenz von Zitaten verfolgen
• Zitierreihenfolge und Positionierung vergleichen
• Spotmuster in Volatilität versus Stabilität

Einrichten des Skripts

In Google Sheets fügen Sie das Skript über Erweiterungen → Apps Script hinzu. Vor der ersten Ausführung legen Sie Ihren API-Schlüssel unter Projekteinstellungen mit dem Eigenschaftsnamen FETCHSERP_API_TOKEN fest. Fügen Sie nach dem Speichern das Skript ein, laden Sie das Sheet neu, und Sie sehen eine neue Menüoption: GEO (FetchSERP) → Fetch AIO & AI Mode.

Kopiert!/**
 * FetchSERP → Google Sheets tracker for AI Overviews (AIO) and AI Mode
 * with rank-like signals and brand presence pivot.
 *
 * Tabs expected/created:
 *  - Keywords: column A header "keyword", then one query per row.
 *  - Brands: column A header "domain" (your brand domains, no www).
 *  - AIO_Results: appended per run (presence + top domains).
 *  - AI_Mode_Results: appended per run (presence + top domains).
 *  - AI_Sources: appended per run (1 row per citation with rank and metadata).
 *  - GEO_AISummary: summary counts + chart (AIO vs AI Mode triggers).
 *  - GEO_BrandPresence: pivot for latest run + chart of rank-1 shares.
 */

const FETCHSERP_BASE = 'https://www.fetchserp.com/api/v1';
const DEFAULT_COUNTRY = 'us';

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('GEO (FetchSERP)')
    .addItem('Fetch AIO & AI Mode', 'runAIOTracking')
    .addToUi();
}

function runAIOTracking() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const token = getApiToken_();
  const keywords = getKeywords_(ss);
  ensureBrandsSheet_(ss); // make sure Brands exists (empty is fine)

  const aioSheet = ensureSheet_(ss, 'AIO_Results', [
    'timestamp', 'keyword', 'country',
    'has_ai_overview', 'source_count', 'top_source_domain', 'all_sources'
  ]);

  const aimodeSheet = ensureSheet_(ss, 'AI_Mode_Results', [
    'timestamp', 'keyword', 'country',
    'has_ai_mode', 'source_count', 'top_source_domain', 'all_sources'
  ]);

  const srcSheet = ensureSheet_(ss, 'AI_Sources', [
    'timestamp', 'keyword', 'country', 'surface', // AIO or AI_MODE
    'rank', 'url', 'domain', 'title', 'site_name'
  ]);

  const now = new Date();
  const aioRows = [];
  const aimodeRows = [];
  const sourceRows = [];

  for (const kw of keywords) {
    const country = DEFAULT_COUNTRY;

    // Primary combined endpoint
    const aiData = callFetchSerp_('serp_ai', { query: kw, country }, token);

    // Optional AI Mode accelerator (US-only, cached)
    let aiModeData = null;
    try {
      aiModeData = callFetchSerp_('serp_ai_mode', { query: kw }, token);
    } catch (e) {
      // OK to ignore; not always necessary
    }

    // ---- AI OVERVIEW ----
    const aioBlock = getBlock_(aiData, 'ai_overview');
    const aioSources = normalizeSources_(aioBlock && aioBlock.sources);
    const aioTop = aioSources.length ? aioSources[0] : null;
    aioRows.push([
      now, kw, country,
      !!aioBlock,
      aioSources.length,
      aioTop ? domainOnly_(aioTop.url || aioTop.site_name || '') : '',
      aioSources.map(s => domainOnly_(s.url || s.site_name || '')).join(' | ')
    ]);

    // push detailed sources with rank
    aioSources.forEach((s, i) => {
      sourceRows.push([
        now, kw, country, 'AIO',
        i + 1,
        s.url || '',
        domainOnly_(s.url || s.site_name || ''),
        s.title || '',
        s.site_name || ''
      ]);
    });

    // ---- AI MODE ----
    const aiModeBlock = extractAiMode_(aiModeData) || extractAiMode_(aiData);
    const aimSources = normalizeSources_(aiModeBlock && aiModeBlock.sources);
    const aimTop = aimSources.length ? aimSources[0] : null;
    aimodeRows.push([
      now, kw, country,
      !!aiModeBlock,
      aimSources.length,
      aimTop ? domainOnly_(aimTop.url || aimTop.site_name || '') : '',
      aimSources.map(s => domainOnly_(s.url || s.site_name || '')).join(' | ')
    ]);

    aimSources.forEach((s, i) => {
      sourceRows.push([
        now, kw, country, 'AI_MODE',
        i + 1,
        s.url || '',
        domainOnly_(s.url || s.site_name || ''),
        s.title || '',
        s.site_name || ''
      ]);
    });

    Utilities.sleep(400); // rate-friendly
  }

  if (aioRows.length) appendRows_(aioSheet, aioRows);
  if (aimodeRows.length) appendRows_(aimodeSheet, aimodeRows);
  if (sourceRows.length) appendRows_(srcSheet, sourceRows);

  buildSummaryAndChart_();
  buildBrandPresencePivotAndChart_(); // NEW
}

/* ----------------------- Helpers & Builders ----------------------- */

function getApiToken_() {
  const props = PropertiesService.getScriptProperties();
  const token = props.getProperty('FETCHSERP_API_TOKEN') || '';
  if (!token) {
    throw new Error('Missing FETCHSERP_API_TOKEN in Script properties. Set it in Project Settings.');
  }
  return token;
}

function getKeywords_(ss) {
  const sh = ss.getSheetByName('Keywords');
  if (!sh) throw new Error('Missing "Keywords" sheet with header "keyword" in A1.');
  const values = sh.getRange(2, 1, Math.max(0, sh.getLastRow() - 1), 1)
    .getValues().flat().map(String).map(s => s.trim()).filter(Boolean);
  if (!values.length) throw new Error('No keywords found under header "keyword" (A2:A).');
  return values;
}

function ensureSheet_(ss, name, headers) {
  let sh = ss.getSheetByName(name);
  if (!sh) sh = ss.insertSheet(name);
  if (sh.getLastRow() === 0) {
    sh.getRange(1, 1, 1, headers.length).setValues([headers]);
    sh.setFrozenRows(1);
  }
  return sh;
}

function ensureBrandsSheet_(ss) {
  let sh = ss.getSheetByName('Brands');
  if (!sh) {
    sh = ss.insertSheet('Brands');
    sh.getRange(1, 1).setValue('domain');
    sh.setFrozenRows(1);
  }
  return sh;
}

function callFetchSerp_(path, params, token) {
  const url = `${FETCHSERP_BASE}/${path}?` + Object.keys(params)
    .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`).join('&');

  const res = UrlFetchApp.fetch(url, {
    method: 'get',
    headers: { 'accept': 'application/json', 'authorization': `Bearer ${token}` },
    muteHttpExceptions: true
  });

  const code = res.getResponseCode();
  const text = res.getContentText();
  if (code = 300) throw new Error(`FetchSERP ${path} error ${code}: ${text}`);

  try { return JSON.parse(text); }
  catch (e) { throw new Error(`FetchSERP ${path} invalid JSON: ${text.slice(0, 300)}…`); }
}

function getBlock_(payload, key) {
  if (!payload) return null;
  const d = payload.data || payload;
  if (d.results && d.results[key]) return d.results[key];
  if (d[key]) return d[key];
  return null;
}

function extractAiMode_(payload) { // tolerate different shapes
  if (!payload) return null;
  const d = payload.data || payload;
  if (d.results && d.results.ai_mode) return d.results.ai_mode;
  if (d.ai_mode) return d.ai_mode;
  return null;
}

function normalizeSources_(sources) {
  if (!Array.isArray(sources)) return [];
  return sources
    .map(s => s || {})
    .map(s => ({
      url: s.url || '',
      title: s.title || '',
      site_name: s.site_name || ''
    }))
    .filter(s => s.url || s.site_name);
}

function domainOnly_(u) {
  try {
    const host = (new URL(u)).hostname || '';
    return host.replace(/^www\./i, '');
  } catch (e) {
    return (u || '').replace(/^www\./i, '');
  }
}

function appendRows_(sheet, rows) {
  sheet.getRange(sheet.getLastRow() + 1, 1, rows.length, rows[0].length).setValues(rows);
}

/** Create or refresh a historical summary tab with counts & share of voice, plus trend chart. */
/** Create or refresh a historical summary tab with counts, SOV, and 7-day rolling averages, plus a trend chart. */
function buildSummaryAndChart_() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sum = ensureSheet_(ss, 'GEO_AISummary', [
    'date',
    'AIO_count', 'AIO_share_of_voice',
    'AI_Mode_count', 'AI_Mode_share_of_voice',
    'keywords_tracked',
    'AIO_count_7dma', 'AI_Mode_count_7dma',
    'AIO_sov_7dma', 'AI_Mode_sov_7dma'
  ]);

  // Clear old rows (keep header)
  if (sum.getLastRow() > 1) {
    sum.getRange(2, 1, sum.getLastRow() - 1, 11).clearContent();
  }

  const aio = ss.getSheetByName('AIO_Results');
  const aim = ss.getSheetByName('AI_Mode_Results');
  const kwSheet = ss.getSheetByName('Keywords');
  if (!aio || !aim || !kwSheet) return;

  const keywordsTracked = Math.max(0, kwSheet.getLastRow() - 1);

  // Build daily counts maps
  const aioCounts = countByDate_(aio, 1, 4); // timestamp col 1, has_ai_overview col 4
  const aimCounts = countByDate_(aim, 1, 4); // timestamp col 1, has_ai_mode col 4

  const allDates = Array.from(new Set([...Object.keys(aioCounts), ...Object.keys(aimCounts)]))
    .sort((a, b) => new Date(a) - new Date(b));

  // Build rows with daily values first
  const rows = allDates.map(date => {
    const aCount = aioCounts[date] || 0;
    const mCount = aimCounts[date] || 0;
    const aSOV = keywordsTracked ? aCount / keywordsTracked : 0;
    const mSOV = keywordsTracked ? mCount / keywordsTracked : 0;
    return [
      date,
      aCount, aSOV,
      mCount, mSOV,
      keywordsTracked,
      null, null, // AIO_count_7dma, AI_Mode_count_7dma (fill after)
      null, null  // AIO_sov_7dma, AI_Mode_sov_7dma (fill after)
    ];
  });

  // Compute 7-day rolling averages (centered on the last 7 days ending at index i)
  const aCountSeries = rows.map(r => r[1]);
  const mCountSeries = rows.map(r => r[3]);
  const aSovSeries   = rows.map(r => r[2]);
  const mSovSeries   = rows.map(r => r[4]);

  const aCount7 = rollingMean_(aCountSeries, 7);
  const mCount7 = rollingMean_(mCountSeries, 7);
  const aSov7   = rollingMean_(aSovSeries,   7);
  const mSov7   = rollingMean_(mSovSeries,   7);

  // Fill the rolling columns
  for (let i = 0; i  sum.removeChart(c));

  const dataHeight = rows.length + 1; // include header
  const chart = sum.newChart()
    .setChartType(Charts.ChartType.LINE)
    .addRange(sum.getRange(1, 1, dataHeight, 10)) // includes counts, SOV, and 7d SOV
    .setPosition(5, 1, 0, 0)
    .setOption('title', 'AIO & AI Mode — Daily Counts and 7-Day SOV Averages')
    .setOption('hAxis', { title: 'Date' })
    .setOption('vAxes', {
      0: { title: 'Keyword Count' },
      1: { title: 'Share of Voice (7-day avg)', format: 'percent' }
    })
    // Series mapping: 0=AIO_count, 1=AIO_SOV, 2=AI_Mode_count, 3=AI_Mode_SOV, 4=keywords_tracked,
    //                 5=AIO_count_7dma, 6=AI_Mode_count_7dma, 7=AIO_sov_7dma, 8=AI_Mode_sov_7dma
    // We'll show daily counts (0,2) on axis 0, hide raw daily SOV (1,3) to reduce noise,
    // show smoothed SOV (7,8) on axis 1, and hide keywords_tracked (4) + count_7dma (5,6) from display.
    .setOption('series', {
      0: { targetAxisIndex: 0 }, // AIO_count (line)
      1: { targetAxisIndex: 1, visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // raw AIO SOV (hidden)
      2: { targetAxisIndex: 0 }, // AI_Mode_count (line)
      3: { targetAxisIndex: 1, visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // raw AI Mode SOV (hidden)
      4: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // keywords_tracked (hidden)
      5: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // AIO_count_7dma (hidden to avoid clutter)
      6: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // AI_Mode_count_7dma (hidden)
      7: { targetAxisIndex: 1 }, // AIO_sov_7dma (smooth)
      8: { targetAxisIndex: 1 }  // AI_Mode_sov_7dma (smooth)
    })
    .setOption('legend', { position: 'bottom' })
    .build();

  sum.insertChart(chart);
}

/** Simple trailing rolling mean with window W; returns array aligned to input length (nulls until window is filled). */
function rollingMean_(arr, W) {
  const out = new Array(arr.length).fill(null);
  let sum = 0;
  for (let i = 0; i = W) sum -= (typeof arr[i - W] === 'number' ? arr[i - W] : 0);
    if (i >= W - 1) out[i] = sum / W;
  }
  return out;
}


/** Helper: count how many rows have TRUE in booleanCol, grouped by date from dateCol. */
function countByDate_(sheet, dateCol, booleanCol) {
  const rows = sheet.getRange(2, 1, sheet.getLastRow() - 1, sheet.getLastColumn()).getValues();
  const counts = {};
  rows.forEach(row => {
    const ts = row[dateCol - 1];
    const has = row[booleanCol - 1];
    if (ts && (has === true || has === 'TRUE')) {
      const d = new Date(ts);
      const dateStr = Utilities.formatDate(d, Session.getScriptTimeZone(), 'yyyy-MM-dd');
      counts[dateStr] = (counts[dateStr] || 0) + 1;
    }
  });
  return counts;
}



function countTrue_(sheet, col) {
  if (!sheet || sheet.getLastRow()  v === true || v === 'TRUE').length;
}

/**
 * Build a pivot for BRAND presence (latest run only).
 * For each surface (AIO / AI_MODE), we compute:
 *  - queries_with_surface: number of keywords where that surface triggered
 *  - queries_brand_cited: number of those keywords where brand domain appears in any citation
 *  - presence_rate = brand_cited / queries_with_surface
 *  - queries_brand_rank1: number where brand is rank 1 citation
 *  - rank1_rate = brand_rank1 / queries_with_surface
 */
function buildBrandPresencePivotAndChart_() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const brands = readBrands_(ss); // array of domains (no www)

  const aioSheet = ss.getSheetByName('AIO_Results');
  const aimSheet = ss.getSheetByName('AI_Mode_Results');
  const srcSheet = ss.getSheetByName('AI_Sources');

  if (!brands.length || !srcSheet || srcSheet.getLastRow()  Set(keywords)
  const surfaceBrandRank1 = { AIO: new Map(), AI_MODE: new Map() }; // brand -> Set(keywords)

  // Iterate source rows for latest timestamp only
  const srcVals = srcSheet.getRange(2, 1, srcSheet.getLastRow() - 1, 9).getValues();
  for (const row of srcVals) {
    const [ts, kw, country, surface, rank, url, domain/*clean*/, title, site_name] = row;
    if (!sameDay_(ts, latest)) continue; // group by day/run timestamp granularity

    const dom = String(domain || '').toLowerCase();
    if (!dom) continue;

    // For presence calculations, only consider keywords that triggered that surface
    if (surface === 'AIO' && !latestAioKeywords.has(kw)) continue;
    if (surface === 'AI_MODE' && !latestAimKeywords.has(kw)) continue;

    // For each brand, check match
    for (const b of brands) {
      if (dom.endsWith(b)) {
        // any-cited
        if (!surfaceBrandAny[surface].has(b)) surfaceBrandAny[surface].set(b, new Set());
        surfaceBrandAny[surface].get(b).add(kw);

        // rank1
        if (rank === 1) {
          if (!surfaceBrandRank1[surface].has(b)) surfaceBrandRank1[surface].set(b, new Set());
          surfaceBrandRank1[surface].get(b).add(kw);
        }
      }
    }
  }

  // Prepare output rows
  const out = [];
  const surfaces = ['AIO', 'AI_MODE'];
  for (const s of surfaces) {
    const queriesWithSurface = (s === 'AIO') ? latestAioKeywords.size : latestAimKeywords.size;
    for (const b of brands) {
      const cited = surfaceBrandAny[s].get(b)?.size || 0;
      const r1 = surfaceBrandRank1[s].get(b)?.size || 0;
      const presenceRate = queriesWithSurface ? (cited / queriesWithSurface) : 0;
      const rank1Rate = queriesWithSurface ? (r1 / queriesWithSurface) : 0;
      out.push([
        b, s, queriesWithSurface, cited, presenceRate, r1, rank1Rate
      ]);
    }
  }

  const pivot = ensureSheet_(ss, 'GEO_BrandPresence', ['brand_domain', 'surface', 'queries_with_surface', 'queries_brand_cited', 'presence_rate', 'queries_brand_rank1', 'rank1_rate']);
  // Clear old data
  if (pivot.getLastRow() > 1) pivot.getRange(2, 1, pivot.getLastRow() - 1, 7).clearContent();
  if (out.length) pivot.getRange(2, 1, out.length, 7).setValues(out);

  // Build/refresh a chart for Rank-1 share per brand per surface
  const charts = pivot.getCharts();
  charts.forEach(c => pivot.removeChart(c));

  // Simple approach: chart all rows, data has both surfaces; users can filter in Sheets UI.
  const chart = pivot.newChart()
    .setChartType(Charts.ChartType.COLUMN)
    .addRange(pivot.getRange(1, 1, Math.max(2, pivot.getLastRow()), 7))
    .setPosition(5, 1, 0, 0)
    .setOption('title', 'Brand Rank-1 Share (latest run)')
    .setOption('series', {
      0: { targetAxisIndex: 0 }, // presence metrics
      1: { targetAxisIndex: 0 },
      2: { targetAxisIndex: 1 }  // rate on secondary axis if desired
    })
    .setOption('legend', { position: 'right' })
    .build();
  pivot.insertChart(chart);
}

/* ---------- Pivot helpers ---------- */

function readBrands_(ss) {
  const sh = ss.getSheetByName('Brands');
  if (!sh || sh.getLastRow()  v.trim().toLowerCase().replace(/^www\./, ''))
    .filter(Boolean);
  return Array.from(new Set(vals));
}

function latestTimestamp_(sheets) {
  let latest = null;
  for (const sh of sheets) {
    if (!sh || sh.getLastRow()  latest) latest = d;
      }
    }
  }
  return latest;
}

function sameDay_(a, b) {
  if (!(a instanceof Date)) a = new Date(a);
  if (!(b instanceof Date)) b = new Date(b);
  return a.getFullYear() === b.getFullYear() &&
         a.getMonth() === b.getMonth() &&
         a.getDate() === b.getDate();
}

function filterKeywordsByTimestampAndBool_(sheet, latestTs, boolColIndex) {
  if (!sheet || sheet.getLastRow() 
/**
 * FetchSERP → Google Sheets tracker for AI Overviews (AIO) and AI Mode
 * with rank-like signals and brand presence pivot.
 *
 * Tabs expected/created:
 *  - Keywords: column A header "keyword", then one query per row.
 *  - Brands: column A header "domain" (your brand domains, no www).
 *  - AIO_Results: appended per run (presence + top domains).
 *  - AI_Mode_Results: appended per run (presence + top domains).
 *  - AI_Sources: appended per run (1 row per citation with rank and metadata).
 *  - GEO_AISummary: summary counts + chart (AIO vs AI Mode triggers).
 *  - GEO_BrandPresence: pivot for latest run + chart of rank-1 shares.
 */

const FETCHSERP_BASE = 'https://www.fetchserp.com/api/v1';
const DEFAULT_COUNTRY = 'us';

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('GEO (FetchSERP)')
    .addItem('Fetch AIO & AI Mode', 'runAIOTracking')
    .addToUi();
}

function runAIOTracking() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const token = getApiToken_();
  const keywords = getKeywords_(ss);
  ensureBrandsSheet_(ss); // make sure Brands exists (empty is fine)

  const aioSheet = ensureSheet_(ss, 'AIO_Results', [
    'timestamp', 'keyword', 'country',
    'has_ai_overview', 'source_count', 'top_source_domain', 'all_sources'
  ]);

  const aimodeSheet = ensureSheet_(ss, 'AI_Mode_Results', [
    'timestamp', 'keyword', 'country',
    'has_ai_mode', 'source_count', 'top_source_domain', 'all_sources'
  ]);

  const srcSheet = ensureSheet_(ss, 'AI_Sources', [
    'timestamp', 'keyword', 'country', 'surface', // AIO or AI_MODE
    'rank', 'url', 'domain', 'title', 'site_name'
  ]);

  const now = new Date();
  const aioRows = [];
  const aimodeRows = [];
  const sourceRows = [];

  for (const kw of keywords) {
    const country = DEFAULT_COUNTRY;

    // Primary combined endpoint
    const aiData = callFetchSerp_('serp_ai', { query: kw, country }, token);

    // Optional AI Mode accelerator (US-only, cached)
    let aiModeData = null;
    try {
      aiModeData = callFetchSerp_('serp_ai_mode', { query: kw }, token);
    } catch (e) {
      // OK to ignore; not always necessary
    }

    // ---- AI OVERVIEW ----
    const aioBlock = getBlock_(aiData, 'ai_overview');
    const aioSources = normalizeSources_(aioBlock && aioBlock.sources);
    const aioTop = aioSources.length ? aioSources[0] : null;
    aioRows.push([
      now, kw, country,
      !!aioBlock,
      aioSources.length,
      aioTop ? domainOnly_(aioTop.url || aioTop.site_name || '') : '',
      aioSources.map(s => domainOnly_(s.url || s.site_name || '')).join(' | ')
    ]);

    // push detailed sources with rank
    aioSources.forEach((s, i) => {
      sourceRows.push([
        now, kw, country, 'AIO',
        i + 1,
        s.url || '',
        domainOnly_(s.url || s.site_name || ''),
        s.title || '',
        s.site_name || ''
      ]);
    });

    // ---- AI MODE ----
    const aiModeBlock = extractAiMode_(aiModeData) || extractAiMode_(aiData);
    const aimSources = normalizeSources_(aiModeBlock && aiModeBlock.sources);
    const aimTop = aimSources.length ? aimSources[0] : null;
    aimodeRows.push([
      now, kw, country,
      !!aiModeBlock,
      aimSources.length,
      aimTop ? domainOnly_(aimTop.url || aimTop.site_name || '') : '',
      aimSources.map(s => domainOnly_(s.url || s.site_name || '')).join(' | ')
    ]);

    aimSources.forEach((s, i) => {
      sourceRows.push([
        now, kw, country, 'AI_MODE',
        i + 1,
        s.url || '',
        domainOnly_(s.url || s.site_name || ''),
        s.title || '',
        s.site_name || ''
      ]);
    });

    Utilities.sleep(400); // rate-friendly
  }

  if (aioRows.length) appendRows_(aioSheet, aioRows);
  if (aimodeRows.length) appendRows_(aimodeSheet, aimodeRows);
  if (sourceRows.length) appendRows_(srcSheet, sourceRows);

  buildSummaryAndChart_();
  buildBrandPresencePivotAndChart_(); // NEW
}

/* ----------------------- Helpers & Builders ----------------------- */

function getApiToken_() {
  const props = PropertiesService.getScriptProperties();
  const token = props.getProperty('FETCHSERP_API_TOKEN') || '';
  if (!token) {
    throw new Error('Missing FETCHSERP_API_TOKEN in Script properties. Set it in Project Settings.');
  }
  return token;
}

function getKeywords_(ss) {
  const sh = ss.getSheetByName('Keywords');
  if (!sh) throw new Error('Missing "Keywords" sheet with header "keyword" in A1.');
  const values = sh.getRange(2, 1, Math.max(0, sh.getLastRow() - 1), 1)
    .getValues().flat().map(String).map(s => s.trim()).filter(Boolean);
  if (!values.length) throw new Error('No keywords found under header "keyword" (A2:A).');
  return values;
}

function ensureSheet_(ss, name, headers) {
  let sh = ss.getSheetByName(name);
  if (!sh) sh = ss.insertSheet(name);
  if (sh.getLastRow() === 0) {
    sh.getRange(1, 1, 1, headers.length).setValues([headers]);
    sh.setFrozenRows(1);
  }
  return sh;
}

function ensureBrandsSheet_(ss) {
  let sh = ss.getSheetByName('Brands');
  if (!sh) {
    sh = ss.insertSheet('Brands');
    sh.getRange(1, 1).setValue('domain');
    sh.setFrozenRows(1);
  }
  return sh;
}

function callFetchSerp_(path, params, token) {
  const url = `${FETCHSERP_BASE}/${path}?` + Object.keys(params)
    .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`).join('&');

  const res = UrlFetchApp.fetch(url, {
    method: 'get',
    headers: { 'accept': 'application/json', 'authorization': `Bearer ${token}` },
    muteHttpExceptions: true
  });

  const code = res.getResponseCode();
  const text = res.getContentText();
  if (code < 200 || code >= 300) throw new Error(`FetchSERP ${path} error ${code}: ${text}`);

  try { return JSON.parse(text); }
  catch (e) { throw new Error(`FetchSERP ${path} invalid JSON: ${text.slice(0, 300)}…`); }
}

function getBlock_(payload, key) {
  if (!payload) return null;
  const d = payload.data || payload;
  if (d.results && d.results[key]) return d.results[key];
  if (d[key]) return d[key];
  return null;
}

function extractAiMode_(payload) { // tolerate different shapes
  if (!payload) return null;
  const d = payload.data || payload;
  if (d.results && d.results.ai_mode) return d.results.ai_mode;
  if (d.ai_mode) return d.ai_mode;
  return null;
}

function normalizeSources_(sources) {
  if (!Array.isArray(sources)) return [];
  return sources
    .map(s => s || Array)
    .map(s => ({
      url: s.url || '',
      title: s.title || '',
      site_name: s.site_name || ''
    }))
    .filter(s => s.url || s.site_name);
}

function domainOnly_(u) {
  try {
    const host = (new URL(u)).hostname || '';
    return host.replace(/^www\./i, '');
  } catch (e) {
    return (u || '').replace(/^www\./i, '');
  }
}

function appendRows_(sheet, rows) {
  sheet.getRange(sheet.getLastRow() + 1, 1, rows.length, rows[0].length).setValues(rows);
}

/** Create or refresh a historical summary tab with counts & share of voice, plus trend chart. */
/** Create or refresh a historical summary tab with counts, SOV, and 7-day rolling averages, plus a trend chart. */
function buildSummaryAndChart_() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sum = ensureSheet_(ss, 'GEO_AISummary', [
    'date',
    'AIO_count', 'AIO_share_of_voice',
    'AI_Mode_count', 'AI_Mode_share_of_voice',
    'keywords_tracked',
    'AIO_count_7dma', 'AI_Mode_count_7dma',
    'AIO_sov_7dma', 'AI_Mode_sov_7dma'
  ]);

  // Clear old rows (keep header)
  if (sum.getLastRow() > 1) {
    sum.getRange(2, 1, sum.getLastRow() - 1, 11).clearContent();
  }

  const aio = ss.getSheetByName('AIO_Results');
  const aim = ss.getSheetByName('AI_Mode_Results');
  const kwSheet = ss.getSheetByName('Keywords');
  if (!aio || !aim || !kwSheet) return;

  const keywordsTracked = Math.max(0, kwSheet.getLastRow() - 1);

  // Build daily counts maps
  const aioCounts = countByDate_(aio, 1, 4); // timestamp col 1, has_ai_overview col 4
  const aimCounts = countByDate_(aim, 1, 4); // timestamp col 1, has_ai_mode col 4

  const allDates = Array.from(new Set([...Object.keys(aioCounts), ...Object.keys(aimCounts)]))
    .sort((a, b) => new Date(a) - new Date(b));

  // Build rows with daily values first
  const rows = allDates.map(date => {
    const aCount = aioCounts[date] || 0;
    const mCount = aimCounts[date] || 0;
    const aSOV = keywordsTracked ? aCount / keywordsTracked : 0;
    const mSOV = keywordsTracked ? mCount / keywordsTracked : 0;
    return [
      date,
      aCount, aSOV,
      mCount, mSOV,
      keywordsTracked,
      null, null, // AIO_count_7dma, AI_Mode_count_7dma (fill after)
      null, null  // AIO_sov_7dma, AI_Mode_sov_7dma (fill after)
    ];
  });

  // Compute 7-day rolling averages (centered on the last 7 days ending at index i)
  const aCountSeries = rows.map(r => r[1]);
  const mCountSeries = rows.map(r => r[3]);
  const aSovSeries   = rows.map(r => r[2]);
  const mSovSeries   = rows.map(r => r[4]);

  const aCount7 = rollingMean_(aCountSeries, 7);
  const mCount7 = rollingMean_(mCountSeries, 7);
  const aSov7   = rollingMean_(aSovSeries,   7);
  const mSov7   = rollingMean_(mSovSeries,   7);

  // Fill the rolling columns
  for (let i = 0; i < rows.length; i++) {
    rows[i][6]  = aCount7[i]; // AIO_count_7dma
    rows[i][7]  = mCount7[i]; // AI_Mode_count_7dma
    rows[i][8]  = aSov7[i];   // AIO_sov_7dma
    rows[i][9]  = mSov7[i];   // AI_Mode_sov_7dma
  }

  if (rows.length) {
    sum.getRange(2, 1, rows.length, rows[0].length).setValues(rows);
  }

  // Rebuild chart: daily counts + smoothed SOV on dual axes
  const charts = sum.getCharts();
  charts.forEach(c => sum.removeChart(c));

  const dataHeight = rows.length + 1; // include header
  const chart = sum.newChart()
    .setChartType(Charts.ChartType.LINE)
    .addRange(sum.getRange(1, 1, dataHeight, 10)) // includes counts, SOV, and 7d SOV
    .setPosition(5, 1, 0, 0)
    .setOption('title', 'AIO & AI Mode — Daily Counts and 7-Day SOV Averages')
    .setOption('hAxis', { title: 'Date' })
    .setOption('vAxes', {
      0: { title: 'Keyword Count' },
      1: { title: 'Share of Voice (7-day avg)', format: 'percent' }
    })
    // Series mapping: 0=AIO_count, 1=AIO_SOV, 2=AI_Mode_count, 3=AI_Mode_SOV, 4=keywords_tracked,
    //                 5=AIO_count_7dma, 6=AI_Mode_count_7dma, 7=AIO_sov_7dma, 8=AI_Mode_sov_7dma
    // We'll show daily counts (0,2) on axis 0, hide raw daily SOV (1,3) to reduce noise,
    // show smoothed SOV (7,8) on axis 1, and hide keywords_tracked (4) + count_7dma (5,6) from display.
    .setOption('series', {
      0: { targetAxisIndex: 0 }, // AIO_count (line)
      1: { targetAxisIndex: 1, visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // raw AIO SOV (hidden)
      2: { targetAxisIndex: 0 }, // AI_Mode_count (line)
      3: { targetAxisIndex: 1, visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // raw AI Mode SOV (hidden)
      4: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // keywords_tracked (hidden)
      5: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // AIO_count_7dma (hidden to avoid clutter)
      6: { visibleInLegend: false, lineWidth: 0, pointsVisible: false }, // AI_Mode_count_7dma (hidden)
      7: { targetAxisIndex: 1 }, // AIO_sov_7dma (smooth)
      8: { targetAxisIndex: 1 }  // AI_Mode_sov_7dma (smooth)
    })
    .setOption('legend', { position: 'bottom' })
    .build();

  sum.insertChart(chart);
}

/** Simple trailing rolling mean with window W; returns array aligned to input length (nulls until window is filled). */
function rollingMean_(arr, W) {
  const out = new Array(arr.length).fill(null);
  let sum = 0;
  for (let i = 0; i < arr.length; i++) {
    sum += (typeof arr[i] === 'number' ? arr[i] : 0);
    if (i >= W) sum -= (typeof arr[i - W] === 'number' ? arr[i - W] : 0);
    if (i >= W - 1) out[i] = sum / W;
  }
  return out;
}


/** Helper: count how many rows have TRUE in booleanCol, grouped by date from dateCol. */
function countByDate_(sheet, dateCol, booleanCol) {
  const rows = sheet.getRange(2, 1, sheet.getLastRow() - 1, sheet.getLastColumn()).getValues();
  const counts = Array;
  rows.forEach(row => {
    const ts = row[dateCol - 1];
    const has = row[booleanCol - 1];
    if (ts && (has === true || has === 'TRUE')) {
      const d = new Date(ts);
      const dateStr = Utilities.formatDate(d, Session.getScriptTimeZone(), 'yyyy-MM-dd');
      counts[dateStr] = (counts[dateStr] || 0) + 1;
    }
  });
  return counts;
}



function countTrue_(sheet, col) {
  if (!sheet || sheet.getLastRow() < 2) return 0;
  const vals = sheet.getRange(2, col, sheet.getLastRow() - 1, 1).getValues().flat();
  return vals.filter(v => v === true || v === 'TRUE').length;
}

/**
 * Build a pivot for BRAND presence (latest run only).
 * For each surface (AIO / AI_MODE), we compute:
 *  - queries_with_surface: number of keywords where that surface triggered
 *  - queries_brand_cited: number of those keywords where brand domain appears in any citation
 *  - presence_rate = brand_cited / queries_with_surface
 *  - queries_brand_rank1: number where brand is rank 1 citation
 *  - rank1_rate = brand_rank1 / queries_with_surface
 */
function buildBrandPresencePivotAndChart_() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const brands = readBrands_(ss); // array of domains (no www)

  const aioSheet = ss.getSheetByName('AIO_Results');
  const aimSheet = ss.getSheetByName('AI_Mode_Results');
  const srcSheet = ss.getSheetByName('AI_Sources');

  if (!brands.length || !srcSheet || srcSheet.getLastRow() < 2) {
    ensureSheet_(ss, 'GEO_BrandPresence', ['brand_domain', 'surface', 'queries_with_surface', 'queries_brand_cited', 'presence_rate', 'queries_brand_rank1', 'rank1_rate']);
    return;
  }

  // Determine latest run timestamp (max timestamp across results)
  const latest = latestTimestamp_([aioSheet, aimSheet, srcSheet].filter(Boolean));
  if (!latest) return;

  // Build per-surface sets of keywords that triggered surface in the latest run
  const latestAioKeywords = new Set(filterKeywordsByTimestampAndBool_(aioSheet, latest, 4)); // has_ai_overview
  const latestAimKeywords = new Set(filterKeywordsByTimestampAndBool_(aimSheet, latest, 4)); // has_ai_mode

  // Build maps for brand presence by keyword and rank1 by keyword (latest run only)
  const surfaceBrandAny = { AIO: new Map(), AI_MODE: new Map() }; // brand -> Set(keywords)
  const surfaceBrandRank1 = { AIO: new Map(), AI_MODE: new Map() }; // brand -> Set(keywords)

  // Iterate source rows for latest timestamp only
  const srcVals = srcSheet.getRange(2, 1, srcSheet.getLastRow() - 1, 9).getValues();
  for (const row of srcVals) {
    const [ts, kw, country, surface, rank, url, domain/*clean*/, title, site_name] = row;
    if (!sameDay_(ts, latest)) continue; // group by day/run timestamp granularity

    const dom = String(domain || '').toLowerCase();
    if (!dom) continue;

    // For presence calculations, only consider keywords that triggered that surface
    if (surface === 'AIO' && !latestAioKeywords.has(kw)) continue;
    if (surface === 'AI_MODE' && !latestAimKeywords.has(kw)) continue;

    // For each brand, check match
    for (const b of brands) {
      if (dom.endsWith(b)) {
        // any-cited
        if (!surfaceBrandAny[surface].has(b)) surfaceBrandAny[surface].set(b, new Set());
        surfaceBrandAny[surface].get(b).add(kw);

        // rank1
        if (rank === 1) {
          if (!surfaceBrandRank1[surface].has(b)) surfaceBrandRank1[surface].set(b, new Set());
          surfaceBrandRank1[surface].get(b).add(kw);
        }
      }
    }
  }

  // Prepare output rows
  const out = [];
  const surfaces = ['AIO', 'AI_MODE'];
  for (const s of surfaces) {
    const queriesWithSurface = (s === 'AIO') ? latestAioKeywords.size : latestAimKeywords.size;
    for (const b of brands) {
      const cited = surfaceBrandAny[s].get(b)?.size || 0;
      const r1 = surfaceBrandRank1[s].get(b)?.size || 0;
      const presenceRate = queriesWithSurface ? (cited / queriesWithSurface) : 0;
      const rank1Rate = queriesWithSurface ? (r1 / queriesWithSurface) : 0;
      out.push([
        b, s, queriesWithSurface, cited, presenceRate, r1, rank1Rate
      ]);
    }
  }

  const pivot = ensureSheet_(ss, 'GEO_BrandPresence', ['brand_domain', 'surface', 'queries_with_surface', 'queries_brand_cited', 'presence_rate', 'queries_brand_rank1', 'rank1_rate']);
  // Clear old data
  if (pivot.getLastRow() > 1) pivot.getRange(2, 1, pivot.getLastRow() - 1, 7).clearContent();
  if (out.length) pivot.getRange(2, 1, out.length, 7).setValues(out);

  // Build/refresh a chart for Rank-1 share per brand per surface
  const charts = pivot.getCharts();
  charts.forEach(c => pivot.removeChart(c));

  // Simple approach: chart all rows, data has both surfaces; users can filter in Sheets UI.
  const chart = pivot.newChart()
    .setChartType(Charts.ChartType.COLUMN)
    .addRange(pivot.getRange(1, 1, Math.max(2, pivot.getLastRow()), 7))
    .setPosition(5, 1, 0, 0)
    .setOption('title', 'Brand Rank-1 Share (latest run)')
    .setOption('series', {
      0: { targetAxisIndex: 0 }, // presence metrics
      1: { targetAxisIndex: 0 },
      2: { targetAxisIndex: 1 }  // rate on secondary axis if desired
    })
    .setOption('legend', { position: 'right' })
    .build();
  pivot.insertChart(chart);
}

/* ---------- Pivot helpers ---------- */

function readBrands_(ss) {
  const sh = ss.getSheetByName('Brands');
  if (!sh || sh.getLastRow() < 2) return [];
  const vals = sh.getRange(2, 1, sh.getLastRow() - 1, 1).getValues().flat()
    .map(String).map(v => v.trim().toLowerCase().replace(/^www\./, ''))
    .filter(Boolean);
  return Array.from(new Set(vals));
}

function latestTimestamp_(sheets) {
  let latest = null;
  for (const sh of sheets) {
    if (!sh || sh.getLastRow() < 2) continue;
    const tsCol = 1; // first col in our schemas
    const vals = sh.getRange(2, tsCol, sh.getLastRow() - 1, 1).getValues().flat();
    for (const v of vals) {
      const d = (v instanceof Date) ? v : new Date(v);
      if (!isNaN(+d)) {
        if (!latest || d > latest) latest = d;
      }
    }
  }
  return latest;
}

function sameDay_(a, b) {
  if (!(a instanceof Date)) a = new Date(a);
  if (!(b instanceof Date)) b = new Date(b);
  return a.getFullYear() === b.getFullYear() &&
         a.getMonth() === b.getMonth() &&
         a.getDate() === b.getDate();
}

function filterKeywordsByTimestampAndBool_(sheet, latestTs, boolColIndex) {
  if (!sheet || sheet.getLastRow() < 2) return [];
  const rows = sheet.getRange(2, 1, sheet.getLastRow() - 1, sheet.getLastColumn()).getValues();
  const out = [];
  for (const r of rows) {
    const ts = r[0];
    const kw = r[1];
    const val = r[boolColIndex - 1];
    if (sameDay_(ts, latestTs) && (val === true || val === 'TRUE')) out.push(kw);
  }
  return out;
}

Von dort aus werden bei jedem Durchlauf Ihre Schlüsselwortliste abgefragt, die Endpunkte aufgerufen, die Ausgabe normalisiert und die Ergebnisse mit Zeitstempel in die entsprechenden Registerkarten eingefügt. Mit der Zeit wird daraus ein vollständiger Datensatz, den Sie ausrichten, in Diagrammen darstellen und analysieren können - im Wesentlichen ein Sichtbarkeits-Dashboard, das Sie steuern können.

Wie sich FetchSERP in den Arbeitsablauf einfügt

Das Skript beginnt mit dem Aufruf von /api/v1/serp_ai, das einen kombinierten Schnappschuss der AI Overview- und AI Mode-Ergebnisse liefert, wann immer diese vorhanden sind. Wenn Sie Abfragen aus den USA ausführen, prüft das Skript auch /api/v1/serp_ai_mode, einen zwischengespeicherten Endpunkt, der AI Mode-Daten schneller liefert. Wenn beide verfügbar sind, wird der zwischengespeicherte AI-Modus bevorzugt.

In der Nutzlast finden Sie normalerweise Folgendes:

• AI-Übersichtsergebnisse gespeichert unter data.results.ai_overview
• AI-Modus-Ergebnisse unter data.results.ai_mode

Jede dieser Quellen enthält eine Reihe von Quellen, die dann in eine saubere Liste von Domänen zerlegt werden. Diese Domänen werden Sie schließlich für Pivot- und Sichtbarkeitsdiagramme verwenden.

Ergebnisse in Blätter schreiben

Das Google Apps Script verbindet sich direkt mit Sheets auf einfache Weise:

• Es wird geprüft, ob die Registerkarte Schlüsselwörter richtig eingerichtet ist.
• Falls nicht vorhanden, werden automatisch die Registerkarten AIO_Results und AI_Mode_Results erstellt.
• Für jeden Abfragelauf wird eine neue Zeile mit dem Zeitstempel, den Präsenzkennzeichen, der Anzahl der Quellen, der am häufigsten zitierten Domäne und einer Liste aller Domänen in diesem Antwortsatz hinzugefügt.

Da neue Zeilen hinzugefügt und nicht überschrieben werden, können Sie nach und nach einen historischen Datensatz erstellen. Im Laufe der Zeit können Sie Metriken wie:

• Der Prozentsatz Ihrer verfolgten Keywords, die eine AI-Übersicht auslösen
• Die am häufigsten zitierten Domänen im AI-Modus nach Woche oder Monat

Diese historische Betrachtung macht aus einmaligen Überprüfungen umsetzbare Erkenntnisse.

Bewährte Praktiken für die Verwendung von FetchSERP

1. Planen Sie für Volatilität: KI-Antworten sind nicht festgelegt. Wiederholte Stichproben und Zeitstempel sind der einzige Weg, um Veränderungen zu erkennen.
2. Vermeiden Sie das Überschreiten von Grenzen: Wenn Sie große Stichwortmengen verfolgen, fügen Sie Pausen ein (z. B. Utilities.sleep(400)) oder teilen Sie sie in Stapel auf.
3. Regionalspezifisch bleiben: Geben Sie bei Abfragen immer einen Ländercode an, da Ihre Daten sonst Standorte vermischen.
4. Erfassen Sie mehr Details: Wenn Sie eine tiefergehende Analyse wünschen, können Sie das Skript so erweitern, dass es auch vollständige URLs, Seitentitel und Herausgebernamen speichert.

Während SaaS-Tools für Unternehmen Ihnen ausgefeilte Dashboards liefern können, bietet Ihnen die Erstellung Ihrer eigenen Pipeline mit FetchSERP Flexibilität und Kontrolle. Für viele Teams ist dies der schnellste Weg, um KI-Transparenz als messbaren, wiederholbaren Prozess zu behandeln.

Wie man Perplexity und Copilot überwacht

Perplexität

Perplexity ist eine der am einfachsten zu messenden Plattformen, da sie ihre Zitate direkt neben der Antwort anzeigt. Erkennungstools können diese Referenzen erfassen, sobald sie gerendert werden. Der Haken an der Sache ist, dass Perplexity sich selten an die eingegebene Frage hält. Es formuliert die Frage stillschweigend um, bevor es die Ergebnisse ausgibt. Das bedeutet, dass ein Teil des Diagnoseprozesses darin besteht, diese umformulierten Abfragen zu erfassen. Ohne sie ist es schwer zu sagen, warum Ihr Inhalt in die engere Wahl gekommen ist oder nicht.

Wenn Sie Perplexity für die Nachverfolgung auslesen, sind diese Regionen am zuverlässigsten:

• Antworttext: erscheint normalerweise in main [data-testid="answer"], main article, oder main .prose. Als Ausweichmöglichkeit können Sie nach Klassen suchen, die Prosa oder Markdown enthalten.
• Liste der Zitate: häufig zu finden in aside [data-testid="source"] oder nav[aria-label*="Sources"] a[href]. Inline-Zitate können als sup a[href] oder a[data-source-id] innerhalb der Antwort selbst erscheinen.
• Bonus-Methode: Perplexity bettet manchmal einen JSON-Status in script[type="application/json"] oder über ein window.__... Hydrationsobjekt ein. Wenn Sie dies analysieren, erhalten Sie eine stabilere Liste von Quellen - komplett mit Titeln, URLs und Autoren, anstatt sich nur auf das sichtbare DOM zu verlassen.

Bing Copilot

Copilot bringt eine weitere Reihe von Herausforderungen mit sich. Copilot stützt sich stark auf den Bing-Index, so dass Ihre grundlegende Bing-Sichtbarkeit einen großen Einfluss darauf hat, ob Sie in den generativen Antworten erscheinen. Im Gegensatz zu Perplexity neigt Copilot dazu, Zitate am Ende seiner Antwort zu verstecken, was ihre Sichtbarkeit verringert. Das Tracking erfordert die Erfassung des gesamten AI-Blocks und die Analyse jedes Links. Durch den Vergleich der Copilot-Zitate mit den Standard-Rankings von Bing für dieselbe Suchanfrage können Sie feststellen, ob Rankings allein die Einbeziehung vorantreiben oder ob andere Autoritätssignale im Spiel sind.

AI-Suchdaten in ein Dashboard verwandeln

Das Endziel all Ihrer Überwachungsmaßnahmen ist ein einziger Ort, an dem Sie sehen können, wie sich Ihre Marke auf allen KI-Oberflächen verhält. Ein gutes Dashboard fasst sowohl die aktiven Überprüfungen, die Sie durchführen, als auch die passiven Crawl-Daten aus Ihren Protokollen zusammen und macht daraus einen klaren Überblick über Ihre Position.

Was das Dashboard zeigen sollte

Ihr Dashboard sollte Ihnen nicht nur sagen, ob Sie zitiert werden - es sollte auch den Kontext erklären. Für jedes Stichwort, das Sie verfolgen, wollen Sie es wissen:

• Wurde eine KI-Übersicht oder ein KI-Modus ausgelöst?
• Wurde auf Ihren Inhalt verwiesen, und wie prominent war er?
• Wie oft sind Sie in der letzten Woche oder im letzten Monat zitiert worden?
• Stimmen die Veränderungen in den Crawl-Mustern des Bots mit diesen Zitaten überein?

Mit dieser Einrichtung können Sie aufhören, über die Sichtbarkeit zu raten, und beginnen, tatsächliche Trends zu erkennen.

Zu verfolgende Schlüsselmetriken

Die nützlichsten Dashboards zeigen:

• Tägliche Zählungen: Anzahl der Schlüsselwörter, die AI Overviews oder AI Mode ausgelöst haben.
• Share of Voice (SOV): Prozentualer Anteil Ihrer Keywords, die in jeder Funktion auftauchen.
• Rollierende Durchschnitte: Sieben-Tage-Trends, die die tägliche Volatilität glätten und den tatsächlichen Kursverlauf zeigen.
• Markenpräsenz: Wo Ihre Domain erscheint und ob Sie an erster Stelle genannt werden oder ganz unten in der Liste stehen.

Aus Daten werden Einsichten

Durch die Verknüpfung von Sichtbarkeitsdaten mit Serverprotokollen können Sie herausfinden, welche Inhaltsaktualisierungen, technischen Korrekturen oder Wettbewerbsverschiebungen den Ausschlag geben. Mit der Zeit hilft Ihnen diese Ursache-Wirkungs-Ansicht nicht nur zu erkennen, ob Sie in den KI-Antworten präsent sind, sondern auch warum. Das sind die Erkenntnisse, die Sie brauchen, um Ihre nächste Optimierungsrunde einzuleiten.

Aufschlüsselung von GEO_AISummary-Daten

Säule	Feld	Was es zeigt
A	Datum	Das Kalenderdatum des Laufs, das dem Zeitstempel entnommen wird
B	AIO_Zahl	Anzahl der verfolgten Keywords, die an diesem Tag eine AI-Übersicht auslösten
C	AIO_SOV	Sprachanteil für KI-Übersichten (AIO_Count ÷ gesamte Keywords)
D	AIMode_Zahl	Anzahl der verfolgten Keywords, die den AI-Modus ausgelöst haben
E	AIModus_SOV	Anteil der Stimme für den AI-Modus (AIMode_Count ÷ gesamte Keywords)
F	Schlüsselwörter_Tracked	Gesamtzahl der Abfragen, die in Ihrer Liste überwacht werden
G	AIO_Zahl_7TageAvg	Rollierender Siebentagesdurchschnitt der AI-Übersichtszählungen
H	AIModus_Zahl_7TageAvg	Gleitender Sieben-Tage-Durchschnitt der AI-Modus-Zählungen
I	AIO_SOV_7DayAvg	Gleitender Sieben-Tage-Durchschnitt des AI-Übersichtsanteils für Sprache
J	AIModus_SOV_7TagAvg	Gleitender Sieben-Tage-Durchschnitt des AI-Modus-Anteils an der Sprache

Einrichten eines GEO-Dashboards in Google Sheets

Das Skript fügt ein einfaches Diagramm ein, aber wenn Sie Ihr eigenes Dashboard in Google Sheets erstellen, haben Sie mehr Kontrolle darüber, wie Sie die Daten anzeigen. Mit ein paar Anpassungen können Sie eine Liste von Zahlen in ein klares Bild der Entwicklung Ihrer KI-Sichtbarkeit verwandeln.

Schritt 1: Organisieren Sie die Daten

Öffnen Sie die Registerkarte GEO_AISummary. Vergewissern Sie sich, dass jede Spalte korrekt beschriftet ist, und sortieren Sie dann nach dem ältesten bis zum neuesten Datum. So bleibt die Zeitleiste übersichtlich, bevor Sie mit der Erstellung des Diagramms beginnen.

Schritt 2: Tägliche Aktivität aufzeichnen

Wählen Sie die Spalten A, B und D (Datum, AIO_Count, AIMode_Count). Fügen Sie ein Diagramm ein - am besten eignet sich hier ein Linien- oder Säulendiagramm.

• X-Achse: Datum
• Reihe 1: AIO_Count
• Reihe 2: AIMode_Count

Geben Sie ihm einen Titel wie "Tägliche KI-Übersicht und KI-Modus-Aktivität".

Schritt 3: Visualisierung des Share of Voice

Markieren Sie die Spalten A, C, E, I und J (Datum, AIO_SOV, AIMode_SOV sowie die 7-Tage-Durchschnittswerte). Fügen Sie ein weiteres Liniendiagramm ein.

• Stellen Sie die rohen täglichen Prozentsätze dar, wenn Sie kurzfristige Schwankungen sehen wollen.
• Stellen Sie die gleitenden Durchschnitte dar, um die längerfristige Entwicklung zu erkennen.

Beschriften Sie es mit "Share of Voice Trends".

Schritt 4: Erstellen der Dashboard-Ansicht

Erstellen Sie ein neues Blatt mit dem Namen "Dashboard". Fügen Sie die beiden Diagramme hinzu, die Sie gerade erstellt haben, und erstellen Sie dann einen kleinen Abschnitt mit einer Zusammenfassung am oberen Rand:

• Aktuelle Zählungen und SOV für heute
• Vergleich mit dem gleitenden Durchschnitt der letzten Woche

Schritt 5: Nachverfolgung im Zeitverlauf

Führen Sie das Skript jeden Tag aus (oder öfter, wenn Sie eine höhere Auflösung benötigen). Da die Daten angehängt und nicht überschrieben werden, erstellen Sie automatisch eine laufende Historie. Über Wochen und Monate hinweg werden sich Muster herauskristallisieren - saisonale Schwankungen, die Auswirkungen von Algorithmusänderungen oder die Ergebnisse Ihrer Optimierungsbemühungen.

Praktische Tipps für zuverlässiges GEO-Tracking

Die Arbeit mit der KI-Suchsichtbarkeit ist von Natur aus chaotisch. Systeme sind probabilistisch, die Ergebnisse ändern sich ständig, und dieselbe Abfrage kann sich von einem Durchlauf zum nächsten unterschiedlich verhalten. Diese Praktiken können Ihnen helfen, sauberere und nützlichere Daten zu erhalten.

Erwarten Sie Volatilität

Gehen Sie nicht von Stabilität aus. KI-Übersichten und der KI-Modus können sich von einem Moment auf den anderen ändern. Deshalb sind regelmäßige Überprüfungen und die Aufzeichnung von Zeitstempeln so wichtig. Das Rauschen ist Teil des Signals.

Abfragevolumen verwalten

Wenn Sie Hunderte von Stichwörtern überwachen, sollten Sie Ihre Anfragen zeitlich staffeln. Fügen Sie Verzögerungen zwischen den Läufen hinzu oder teilen Sie große Listen in kleinere Stapel auf. Dadurch wird verhindert, dass Sie an Ratengrenzen stoßen, und Ihre Datenerfassung bleibt konsistent.

Regionalspezifisch sein

Geben Sie bei Abfragen immer einen Ländercode an. Andernfalls könnten Ihre Ergebnisse geografische Regionen vermischen, was die Interpretation von Veränderungen im Laufe der Zeit erschwert.

Mehr als nur Domains verfolgen

Domains sind ein guter Ausgangspunkt, aber manchmal braucht man mehr Details. Erfassen Sie vollständige URLs, Seitentitel und Herausgebernamen, wenn es darauf ankommt. So können Sie genau sehen, welche Assets Sichtbarkeit erlangen.

Rohdaten aufbewahren

KI-Plattformen ändern ihre Ausgaben häufig. Wenn Sie rohe HTML- oder JSON-Antworten aufbewahren, können Sie ältere Daten erneut verarbeiten, wenn Parser ausfallen oder wenn Sie später neue Felder extrahieren müssen.

Schlussfolgerung

Die generative Suche hat das Handbuch für die Messung der Sichtbarkeit neu geschrieben. Rankings und Klicks allein erfassen nicht mehr die ganze Geschichte - die eigentliche Frage ist, ob Ihre Marke in den Antworten, die Nutzer tatsächlich sehen, genannt wird. Durch die Kombination von aktiver Erkennung mit der Analyse von Serverprotokollen, der Überwachung von KI-Crawlern und der Erstellung eines Dashboards, das sowohl tägliche Zählungen als auch langfristige Trends verfolgt, können Sie ein undurchsichtiges System in messbare Erkenntnisse verwandeln.

Bei der Arbeit geht es nicht nur darum, die Zahlen steigen zu sehen. Es geht darum, diese Zitate mit echten Geschäftsergebnissen zu verknüpfen: Konversionen, Umsatz und Wachstum. Das ist es, was Sichtbarkeit in Wert verwandelt. Mit einem konsistenten Rahmen für die Nachverfolgung können Sie Ihre Präsenz in der KI-Suche nicht mehr nur erahnen. Sie treffen fundierte Entscheidungen, die Ihre Marke in die wichtigen Konversationen bringen.

Häufig gestellte Fragen

1. Warum ist es so schwierig, die Sichtbarkeit von KI in der Suche zu verfolgen?

Da die KI-Antworten jedes Mal neu generiert werden, können sich die Ergebnisse von einem Lauf zum nächsten ändern. Anders als bei herkömmlichen Rankings gibt es keine feste Position, auf die man sich verlassen kann, was eine kontinuierliche Überwachung unerlässlich macht.

2. Wie oft sollte ich Tracking-Skripte ausführen?

Bei einer kleinen Anzahl von Schlüsselwörtern erfassen mehrere Durchläufe pro Tag die Volatilität. Bei größeren Listen reichen in der Regel tägliche Durchläufe aus, um eine zuverlässige Trendlinie zu erstellen.

3. Welche Rolle spielen die Serverprotokolle bei der GEO-Analyse?

Serverprotokolle zeigen, wann AI-Bots Ihre Seiten crawlen. Die Korrelation von Crawling-Aktivitäten mit Zitationsdaten hilft Ihnen zu verstehen, wie Abrufe mit der Sichtbarkeit zusammenhängen.

4. Muss ich sowohl die KI-Übersicht als auch den KI-Modus verfolgen?

Ja. Sie verhalten sich unterschiedlich, und Ihre Marke kann in der einen Oberfläche auftauchen, in der anderen aber nicht. Wenn Sie beide Oberflächen verfolgen, erhalten Sie ein vollständiges Bild Ihrer Google AI-Präsenz.

5. Ist Perplexity einfacher zu messen als Google?

In gewisser Weise, ja. Perplexity zeigt Zitate transparent an, schreibt aber auch Abfragen im Hintergrund um, so dass die Erfassung umformulierter Fragen genauso wichtig ist wie die Erfassung sichtbarer Quellen.