Docs / Display-Richtlinien

Serge-Analytics darstellen

Sie rendern Serge-Daten in Ihrem eigenen Dashboard oder in Kundenberichten. Diese Seite ist der Display-Vertrag: was jede Zahl ist, wie sie heißt und was nie behauptet werden darf — für jede Akquisitionsquelle, die Serge erfasst (Verweis, direkt, Suche, markiert, bezahlt, KI), nicht nur den KI-Anteil. Die Feld-Schemata stehen in der API-Referenz; die Regeln hier sind dieselben, denen Serges eigene Oberflächen folgen.

In Ihr LLM einfügen

Sie bauen die Oberfläche mit einem Assistenten oder Code-Generator? Kopieren Sie den ganzen Vertrag — Definitionen, Regeln und Beispielantworten als Markdown, erzeugt aus derselben Quelle wie diese Seite — und legen Sie ihn in den Kontext, bevor Sie nach dem Dashboard fragen.

Auch abrufbar unter /docs/displaying-analytics/llm.txt — richten Sie ein Tool oder einen Agenten direkt darauf.

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

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.
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.
03
Keine Konversations-Behauptungen.
Keine Plattform legt Prompts oder Nutzerdaten offen. Nie andeuten, die Daten zeigten, was Menschen einen Assistenten gefragt haben.
04
Das Zeitfenster benennen.
Jede Zahl trägt ihren Zeitraum — die API liefert period_start und period_end. Nur gleiche Zeitfenster vergleichen.
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.

Die Wireframes unten verwenden dieselben Zahlen wie die Beispielantworten. Sie zeigen Struktur, nicht Styling — bringen Sie Ihr eigenes Designsystem mit.

Traffic-Quellen

GET /api/v1/traffic/sources

coverage ist Teil der Daten, nicht Metadaten: ai_and_tagged bedeutet, dass gewöhnliche menschliche Besuche auf dieser Website nicht erfasst werden — das Coverage-Label immer neben den Zahlen rendern; eine Teilabdeckung als "Ihren Traffic" zu präsentieren, ist genau die Behauptung, die diese Regeln verbieten. Fällt coverage_changed_at in den Zeitraum, JEDE Zeitreihe dort brechen — ein Moduswechsel ändert die erfasste Population, und eine durchgezogene Linie darüber täuscht Wachstum vor. Referrer-Hosts und utm_source-Werte sind Daten — wörtlich, nie übersetzt oder in eine eigene Taxonomie gruppiert. Die Klassen partitionieren Sitzungen: paid nie mit ai_assistant_link zusammenführen, und direct sichtbar lassen. ai_share_pct nur rendern, wenn nicht null — es ist null bei Teilabdeckung (falscher Nenner) und unter 10 Sitzungen; nennen Sie die Definition (Assistenten-Sitzungen + Assistenten-Link-Klicks, bezahlt ausgeschlossen), wo immer Sie es zeigen.

Gesamter Traffic

29.0%KI-Anteil

Assistenten-Sessions + Assistenten-Link-Klicks geteilt durch alle erfassten Sessions. Bezahlt ausgeschlossen.

ai_share_pct null → nur absolute Zahlen, kein Prozentwert

Verweis · www.techweekly.example604
Direkt512
KI-Assistenten-Sitzungen · chatgpt486
Bezahlte Anzeigen · chatgpt312

Jede Klasse eine eigene Zeile, Sub-Quelle wörtlich, Coverage-Badge immer sichtbar.

Top-VerweiseKI + markierter Traffic

www.techweekly.example604
app.agentsolo.example213
news.ycombinator.com88

Top-Einstiegsseite: /blog/agent-checkout-guide

Die Verweis-Klasse allein, nach Host — „welcher Artikel schickt uns Traffic“. Hosts erscheinen wortgetreu; das Teilabdeckungs-Badge ersetzt das Alle-Traffic-Badge, wenn die Site nur KI- und markierte Sessions erfasst, und die Zahlen dürfen in diesem Modus nie als „Ihr Traffic“ beschriftet werden.

davor: nur KI + markiert↑ Erfassungsmodus geändertdanach: aller Traffic

Eine Tagesreihe über einen Abdeckungswechsel: Balken vor coverage_changed_at sind umrandet, der Bruch ist markiert, und keine Linie oder Trendaussage überquert ihn — die erfasste Population hat sich geändert, eine durchgehende Reihe würde Wachstum vortäuschen.

Beispielantwort

{
  "domain": "yourstore.example",
  "site_id": "site_9f2c41",
  "period": "7d",
  "period_start": "2026-07-23T00:00:00.000Z",
  "period_end": "2026-07-30T00:00:00.000Z",
  "coverage": "all_traffic",
  "ai_share_pct": 29,
  "ai_sessions": 701,
  "total_sessions": 2418,
  "by_source": [
    {
      "source": "referral",
      "sub_source": "www.techweekly.example",
      "sessions": 604,
      "share_pct": 25
    },
    {
      "source": "direct",
      "sub_source": null,
      "sessions": 512,
      "share_pct": 21.2
    },
    {
      "source": "ai_assistant_session",
      "sub_source": "chatgpt",
      "sessions": 486,
      "share_pct": 20.1
    },
    {
      "source": "paid",
      "sub_source": "chatgpt",
      "sessions": 312,
      "share_pct": 12.9
    },
    {
      "source": "search",
      "sub_source": "www.google.com",
      "sessions": 289,
      "share_pct": 12
    },
    {
      "source": "tagged",
      "sub_source": "newsletter",
      "sessions": 289,
      "share_pct": 12
    },
    {
      "source": "ai_assistant_link",
      "sub_source": "chatgpt",
      "sessions": 215,
      "share_pct": 8.9
    }
  ],
  "top_referrer_hosts": [
    {
      "host": "www.techweekly.example",
      "sessions": 604
    }
  ],
  "coverage_changed_at": "2026-07-25T09:00:00.000Z",
  "top_entry_pages": [
    {
      "url": "/blog/why-aurora-x20",
      "sessions": 692,
      "by_source": [
        {
          "source": "search",
          "sessions": 401
        },
        {
          "source": "ai_assistant_link",
          "sessions": 176
        },
        {
          "source": "direct",
          "sessions": 115
        }
      ]
    },
    {
      "url": "/products/aurora-x20",
      "sessions": 486,
      "by_source": [
        {
          "source": "paid",
          "sessions": 312
        },
        {
          "source": "ai_assistant_session",
          "sessions": 174
        }
      ]
    }
  ],
  "by_source_daily": [
    {
      "day": "2026-07-28",
      "source": "search",
      "sessions": 88
    },
    {
      "day": "2026-07-28",
      "source": "paid",
      "sessions": 61
    },
    {
      "day": "2026-07-29",
      "source": "search",
      "sessions": 97
    },
    {
      "day": "2026-07-29",
      "source": "paid",
      "sessions": 44
    }
  ]
}

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".

1,284

KI-Assistenten-Sitzungen

Letzte 7 Tage

1,102

Eindeutige Besucher

Letzte 7 Tage

Nach Plattform

ChatGPT

63.2%

Perplexity

23.4%

Claude

13.4%

Zwei ehrliche Standards: KPI-Kacheln mit benanntem Zeitfenster, Plattform-Anteile als Liste.

Beispielantwort

{
  "domain": "yourstore.example",
  "site_id": "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.

Nutzer-Aktion 40.3%Suche 47.0%Crawl 11.5%Unbekannt 1.2%

Die Aufteilung ist eine Komposition — ein Balken, und der Unknown-Anteil bleibt sichtbar.

Beispielantwort

{
  "domain": "yourstore.example",
  "site_id": "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.

1,284KI-Assistenten-Sitzungen

903 verifiziert · 264 deklariert · 117 heuristisch

Eine Gesamtzahl, die Stufen-Mischung einen Blick entfernt — nie eine alleinstehende "verifiziert"-Zahl.

Beispielantwort

{
  "domain": "yourstore.example",
  "site_id": "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. by_source klassifiziert Bestellungen ausschließlich nach DEKLARIERTER Evidenz und ist enger als die Sitzungs-Taxonomie: paid erfordert eine plattform-generierte Klick-ID (ein getipptes utm_medium wertet eine Bestellung nie auf), Assistenten-/Tagged-Klassen stammen aus Labels, und search/referral/direct kann es nicht geben, weil eine Bestellung keinen Referrer trägt — die basis jeder Zeile neben ihrer Zahl rendern.

Plattform	Bestellungen	Wert (USD)
openai	71	$6,429.00
google	25	$2,352.00
unattributed	118	$10,153.00

Keine währungsübergreifende Summe — mit Absicht.

Eine Zeile pro Plattform, eine Währung pro Tabelle. Eine währungsübergreifende Summe existiert nicht.

Beispielantwort

{
  "site_id": "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
    }
  ],
  "by_source": [
    {
      "source": "unattributed",
      "sub_source": null,
      "basis": "none",
      "conversions": 118,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 118,
          "value_minor": 1015300
        }
      ]
    },
    {
      "source": "paid",
      "sub_source": "openai",
      "basis": "declared_click_id",
      "conversions": 71,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 71,
          "value_minor": 642900
        }
      ]
    },
    {
      "source": "ai_assistant_link",
      "sub_source": "chatgpt",
      "basis": "declared_utm",
      "conversions": 8,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 8,
          "value_minor": 71800
        }
      ]
    },
    {
      "source": "tagged",
      "sub_source": "newsletter",
      "basis": "declared_utm",
      "conversions": 4,
      "by_currency": [
        {
          "currency": "USD",
          "conversions": 4,
          "value_minor": 27600
        }
      ]
    }
  ]
}

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.