Afficher les analytics Serge
Vous affichez des données Serge dans votre propre dashboard ou dans des rapports clients. Cette page est le contrat d'affichage : ce qu'est chaque nombre, comment le nommer, et ce qu'il ne faut jamais affirmer. Les structures de champs sont dans la référence API ; les règles ici sont celles que suivent les propres surfaces de Serge.
Trois populations, jamais confondues
Serge mesure trois choses différentes. La plupart des erreurs d'affichage consistent à donner à l'une l'étiquette d'une autre.
- Sessions d'assistants IA
- Un assistant actif sur le site lui-même — qui consulte, navigue ou agit pour un utilisateur. C'est ce que comptent les endpoints /traffic.
- Clics assistants — organiques
- Une personne qui a cliqué sur un lien dans un assistant et atterri sur le site. ChatGPT marque ses liens sortants ; Serge compte les atterrissages. Pas des publicités.
- Clics publicitaires — payants
- Une personne qui a cliqué sur un placement payant, identifié par un ID de clic de plateforme ou un utm_medium payant explicite. Un atterrissage qui porte simplement des paramètres UTM n'est pas un clic publicitaire.
Payant et organique peuvent être côte à côte. Ils ne partagent jamais un nombre, ni une étiquette.
Règles de formulation
- 01
Mesuré, pas causé.
Serge compte ce qui a atterri et ce que ça a fait sur le site. "12 commandes issues de clics publicitaires ChatGPT mesurés" est défendable ; "ChatGPT a généré 12 commandes" affirme une incrémentalité que personne n'a mesurée.
- 02
Un décompte est un décompte.
Pas de barres d'erreur ni de ± sur un décompte. Sous une dizaine d'événements, montrez le nombre brut et omettez les taux — un pourcentage d'apparence précise sur un échantillon de la taille du bruit induit en erreur.
- 03
Aucune affirmation sur les conversations.
Aucune plateforme n'expose les prompts ni les données utilisateur. Ne laissez jamais entendre que les données montrent ce que les gens ont demandé à un assistant.
- 04
Nommer la fenêtre.
Chaque nombre porte sa période — l'API renvoie period_start et period_end. Ne comparez que des fenêtres égales.
- 05
Noms de plateformes tels quels.
ChatGPT, Perplexity, Claude, Gemini, Copilot — les noms de marque ne se traduisent pas, ne s'abrègent pas et ne se fondent pas dans une taxonomie maison.
Le même nombre, dit honnêtement
À éviter"ChatGPT a généré 4 200 $ de revenus."
À faire"4 200 $ de commandes issues de clics publicitaires ChatGPT mesurés (30 jours)."
À éviter"Trafic IA vérifié : 1 020 sessions" — alors que 117 sont des détections heuristiques.
À faire"1 020 sessions d'assistants IA — 903 vérifiées, 117 heuristiques."
À éviter"Taux de complétion de 100 %" — sur une seule session.
À faire"1 session, 1 complétée." Les taux commencent quand l'échantillon peut les porter.
Par endpoint : points d'attention, avec exemple
Les exemples ci-dessous sont les mêmes exemples validés que publie la référence API — ils ne peuvent pas dériver du contrat. Les notes ne couvrent que ce qui compte une fois le nombre devant un humain.
Vue d'ensemble du trafic
GET /api/v1/traffic/overview
Sessions et visiteurs uniques sont des nombres différents — étiquetez celui que vous montrez. share_pct arrive calculé ; ne le recalculez pas sur un sous-ensemble filtré. Dans by_outcome, "abandoned" signifie que la session s'est terminée sans aboutir — pas qu'une erreur s'est produite. median_duration_ms est une médiane : étiquetez "médiane", jamais "moyenne".
{
"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
}Répartition par intention
GET /api/v1/traffic/purpose-split
user_action est un assistant agissant pour quelqu'un ; search est une récupération pour une réponse ; crawl est de l'indexation. Gardez la part unknown visible — la fondre dans une autre catégorie surestime la certitude. La répartition est une composition : une barre empilée ou une liste de parts, pas quatre KPI déconnectés.
{
"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
}
]
}Répartition par vérification
GET /api/v1/traffic/verification
verified, declared et heuristic sont des niveaux de preuve, du plus fort au plus faible. Une session heuristique ne s'affiche jamais sous l'étiquette "vérifié". Si vous montrez un total, gardez la répartition des niveaux à un regard.
{
"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"
}
]
}Vue d'ensemble de l'attribution
GET /api/v1/attribution/overview
Ne sommez jamais des valeurs entre devises — affichez une ligne par devise (value_minor est en unités mineures). Il n'y a pas de champ ROAS, à dessein : Serge ne lit pas encore les dépenses, et le calculer soi-même sur des données partielles produit un faux nombre. La base d'attribution compte : un ID de clic de plateforme est une preuve solide, un label UTM est auto-déclaré — gardez cette distinction accessible.
{
"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
}
]
}Structures, authentification et limites sont dans la référence API. S'il manque une métrique que vous voulez afficher, demandez — la règle que vous recevrez correspondra à la façon dont Serge affiche lui-même ces données.