Zum Inhalt springen
Docs / Display-Richtlinien

Serge-Analytics darstellen

Sie rendern Serge-Daten in Ihrem eigenen Dashboard oder in Kunden-Reports. Diese Seite ist der Display-Vertrag: was jede Zahl ist, wie sie heißt und was nie behauptet werden darf. Die Feld-Strukturen stehen in der API-Referenz; die Regeln hier sind dieselben, denen Serges eigene Oberflächen folgen.

Drei Populationen, nie vermischt

Serge misst drei verschiedene Dinge. Die meisten Darstellungsfehler bestehen darin, dass eines davon das Etikett eines anderen trägt.

KI-Assistenten-Sitzungen
Ein Assistent, der selbst auf der Website aktiv ist — abrufend, navigierend oder im Auftrag eines Nutzers handelnd. Das zählen die /traffic-Endpunkte.
Assistenten-Klicks — organisch
Eine Person, die in einem Assistenten auf einen Link geklickt hat und auf der Website gelandet ist. ChatGPT markiert seine ausgehenden Links; Serge zählt die Landungen. Keine Anzeigen.
Anzeigenklicks — bezahlt
Eine Person, die auf eine bezahlte Platzierung geklickt hat — erkennbar an einer Plattform-Klick-ID oder einem expliziten bezahlten utm_medium. Eine Landung, die lediglich UTM-Parameter trägt, ist kein Anzeigenklick.

Bezahlt und organisch dürfen nebeneinander stehen. Sie teilen sich nie eine Zahl und nie ein Etikett.

Formulierungsregeln

  1. 01

    Gezählt, nicht verursacht.

    Serge zählt, was gelandet ist und was es auf der Website getan hat. "12 Bestellungen aus gezählten ChatGPT-Anzeigenklicks" ist belegbar; "ChatGPT hat 12 Bestellungen gebracht" behauptet eine Inkrementalität, die niemand gemessen hat.

  2. 02

    Zählwerte sind Zählwerte.

    Keine Fehlerbalken oder ± an einem Zählwert. Unter rund zehn Ereignissen die nackte Zahl zeigen und auf Raten verzichten — ein präzise wirkender Prozentwert auf einer rauschgroßen Stichprobe führt in die Irre.

  3. 03

    Keine Konversations-Behauptungen.

    Keine Plattform legt Prompts oder Nutzerdaten offen. Nie andeuten, die Daten zeigten, was Menschen einen Assistenten gefragt haben.

  4. 04

    Das Zeitfenster benennen.

    Jede Zahl trägt ihren Zeitraum — die API liefert period_start und period_end. Nur gleiche Zeitfenster vergleichen.

  5. 05

    Plattformnamen wörtlich.

    ChatGPT, Perplexity, Claude, Gemini, Copilot — Markennamen werden nicht übersetzt, abgekürzt oder in eine eigene Taxonomie gefaltet.

Dieselbe Zahl, ehrlich gesagt

Nicht so"ChatGPT hat $4.200 Umsatz gebracht."

So"$4.200 an Bestellungen aus gezählten ChatGPT-Anzeigenklicks (30 Tage)."

Nicht so"Verifizierter KI-Traffic: 1.020 Sitzungen" — wenn 117 davon heuristische Erkennungen sind.

So"1.020 KI-Assistenten-Sitzungen — 903 verifiziert, 117 heuristisch."

Nicht so"100 % Abschlussrate" — aus einer einzigen Sitzung.

So"1 Sitzung, 1 abgeschlossen." Raten beginnen, wenn die Stichprobe sie trägt.

Pro Endpunkt: worauf achten, mit Beispiel

Die Beispiele unten sind dieselben validierten Beispiele, die die API-Referenz veröffentlicht — sie können nicht vom Vertrag abweichen. Die Hinweise decken nur ab, was zählt, sobald die Zahl einen Menschen erreicht.

Traffic-Übersicht

GET /api/v1/traffic/overview

Sitzungen und eindeutige Besucher sind verschiedene Zahlen — beschriften Sie die, die Sie zeigen. share_pct kommt berechnet; nicht auf einer gefilterten Teilmenge neu berechnen. In by_outcome bedeutet "abandoned", dass die Sitzung ohne Abschluss endete — nicht, dass ein Fehler auftrat. median_duration_ms ist ein Median: als "Median" beschriften, nie als "Durchschnitt".

{
  "domain": "yourstore.example",
  "site_id": "srg_site_9f2c41",
  "period": "7d",
  "period_start": "2026-07-23T00:00:00.000Z",
  "period_end": "2026-07-30T00:00:00.000Z",
  "total_sessions": 1284,
  "unique_visitors": 1102,
  "by_platform": [
    {
      "platform": "chatgpt",
      "sessions": 812,
      "share_pct": 63.2
    },
    {
      "platform": "perplexity",
      "sessions": 301,
      "share_pct": 23.4
    },
    {
      "platform": "claude",
      "sessions": 171,
      "share_pct": 13.4
    }
  ],
  "by_outcome": [
    {
      "outcome": "completed",
      "sessions": 402
    },
    {
      "outcome": "abandoned",
      "sessions": 882
    }
  ],
  "top_pages": [
    {
      "entry_url": "/products/aurora-x20",
      "sessions": 486
    },
    {
      "entry_url": "/collections/headphones",
      "sessions": 210
    }
  ],
  "median_duration_ms": 42150
}

Zweck-Aufteilung

GET /api/v1/traffic/purpose-split

user_action ist ein Assistent, der im Auftrag von jemandem handelt; search ist Abruf für eine Antwort; crawl ist Indexierung. Den unknown-Anteil sichtbar lassen — ihn in eine andere Kategorie zu falten, überzeichnet die Gewissheit. Die Aufteilung ist eine Komposition: ein gestapelter Balken oder eine Anteilsliste, nicht vier getrennte KPIs.

{
  "domain": "yourstore.example",
  "site_id": "srg_site_9f2c41",
  "period": "7d",
  "period_start": "2026-07-23T00:00:00.000Z",
  "period_end": "2026-07-30T00:00:00.000Z",
  "total_sessions": 1284,
  "user_action_sessions": 517,
  "search_sessions": 604,
  "crawl_sessions": 148,
  "unknown_sessions": 15,
  "by_purpose": [
    {
      "purpose": "user_action",
      "sessions": 517,
      "share_pct": 40.3
    },
    {
      "purpose": "search",
      "sessions": 604,
      "share_pct": 47
    },
    {
      "purpose": "crawl",
      "sessions": 148,
      "share_pct": 11.5
    }
  ]
}

Verifikations-Aufschlüsselung

GET /api/v1/traffic/verification

verified, declared und heuristic sind Evidenzstufen, stärkste zuerst. Eine heuristische Sitzung erscheint nie unter dem Etikett "verifiziert". Wenn Sie eine Gesamtzahl zeigen, bleibt die Stufen-Mischung einen Blick entfernt.

{
  "domain": "yourstore.example",
  "site_id": "srg_site_9f2c41",
  "period": "7d",
  "period_start": "2026-07-23T00:00:00.000Z",
  "period_end": "2026-07-30T00:00:00.000Z",
  "total_sessions": 1284,
  "verified_sessions": 903,
  "declared_sessions": 264,
  "heuristic_sessions": 117,
  "by_platform": [
    {
      "platform": "chatgpt",
      "sessions": 812,
      "verified": 690,
      "declared": 96,
      "heuristic": 26,
      "tier": "verified"
    }
  ]
}

Attributions-Übersicht

GET /api/v1/attribution/overview

Werte nie über Währungen hinweg summieren — eine Zeile pro Währung rendern (value_minor ist in Minor Units). Es gibt bewusst kein ROAS-Feld: Serge liest noch keine Ausgaben, und ein selbst berechneter Wert aus Teildaten ergibt eine falsche Zahl. Die Attributionsbasis zählt: eine Plattform-Klick-ID ist harte Evidenz, ein UTM-Label ist selbst deklariert — diese Unterscheidung erreichbar halten.

{
  "site_id": "srg_site_9f2c41",
  "domain": "yourstore.example",
  "period": "30d",
  "period_start": "2026-06-30T00:00:00.000Z",
  "period_end": "2026-07-30T00:00:00.000Z",
  "total_conversions": 214,
  "attributed_conversions": 96,
  "unattributed_conversions": 118,
  "by_currency": [
    {
      "currency": "USD",
      "conversions": 214,
      "value_minor": 1893400
    }
  ],
  "by_platform": [
    {
      "platform": "openai",
      "conversions": 71,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 71,
          "value_minor": 642900
        }
      ]
    },
    {
      "platform": "unattributed",
      "conversions": 118,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 118,
          "value_minor": 1015300
        }
      ]
    },
    {
      "platform": "google",
      "conversions": 25,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 25,
          "value_minor": 235200
        }
      ]
    }
  ],
  "by_basis": [
    {
      "basis": "none",
      "conversions": 118
    },
    {
      "basis": "declared_click_id",
      "conversions": 84
    },
    {
      "basis": "declared_utm",
      "conversions": 12
    }
  ]
}

Strukturen, Auth und Limits stehen in der API-Referenz. Fehlt hier eine Metrik, die Sie darstellen wollen, fragen Sie — die Regel, die Sie bekommen, entspricht dem, wie Serge dieselben Daten selbst rendert.