Afficher les analytics Serge
Vous affichez des données Serge dans votre propre tableau de bord ou dans des rapports clients. Cette page est le contrat d'affichage : ce qu'est chaque chiffre, comment le nommer et ce qu'il ne faut jamais affirmer — pour chaque source d'acquisition enregistrée par Serge (référent, direct, recherche, balisé, payant, IA), pas seulement la part IA. Les schémas de champs sont dans la référence API ; les règles ici sont celles que suivent les propres surfaces de Serge.
À coller dans votre LLM
Vous construisez la surface avec un assistant ou un générateur de code ? Copiez le contrat entier — définitions, règles et exemples de réponses en markdown, généré depuis la même source que cette page — et placez-le dans le contexte avant de demander le dashboard.
Aussi récupérable sur /docs/displaying-analytics/llm.txt — pointez-y directement un outil ou un agent.
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.
Les maquettes ci-dessous utilisent les mêmes nombres que les exemples de réponses. Elles montrent la structure, pas le style — apportez votre propre design system.
Sources de trafic
GET /api/v1/traffic/sources
coverage fait partie des données, pas des métadonnées : ai_and_tagged signifie que les visites humaines ordinaires ne sont pas enregistrées sur ce site — affichez toujours le label de couverture à côté des nombres ; présenter une couverture partielle comme "votre trafic" est exactement l'affirmation que ces règles interdisent. Quand coverage_changed_at tombe dans la période, CASSEZ chaque série temporelle à ce point — un changement de mode change la population enregistrée, et une ligne continue par-dessus simule de la croissance. Les hôtes référents et les valeurs utm_source sont des données — telles quelles, jamais traduites ni regroupées dans une taxonomie maison. Les classes partitionnent les sessions : ne fusionnez jamais paid avec ai_assistant_link, et gardez direct visible. ai_share_pct ne s'affiche que s'il est non nul — il est nul en couverture partielle (mauvais dénominateur) et sous 10 sessions ; énoncez sa définition (sessions d'assistants + clics de liens d'assistants, payant exclu) partout où vous l'affichez.
Sessions d'assistants + clics de liens d'assistants sur toutes les sessions enregistrées. Payant exclu.
ai_share_pct null → chiffres bruts, pas de pourcentage
- Référent · www.techweekly.example604
- Direct512
- Sessions d'assistants IA · chatgpt486
- Publicités payantes · chatgpt312
- www.techweekly.example604
- app.agentsolo.example213
- news.ycombinator.com88
Première page d'entrée: /blog/agent-checkout-guide
Exemple de réponse
{
"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
}
]
}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".
Exemple de réponse
{
"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
}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.
Exemple de réponse
{
"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
}
]
}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.
903 vérifiées · 264 déclarées · 117 heuristiques
Exemple de réponse
{
"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"
}
]
}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. by_source classe les commandes uniquement d'après des preuves DÉCLARÉES et est plus étroit que la taxonomie des sessions : paid exige un ID de clic émis par la plateforme (un utm_medium saisi ne surclasse jamais une commande), les classes assistant/tagged viennent d'étiquettes, et search/referral/direct ne peuvent pas exister car une commande ne porte pas de référent — affichez la basis de chaque ligne à côté de son nombre.
| Plateforme | Commandes | Valeur (USD) |
|---|---|---|
| openai | 71 | $6,429.00 |
| 25 | $2,352.00 | |
| unattributed | 118 | $10,153.00 |
Pas de total inter-devises — à dessein.
Exemple de réponse
{
"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
}
]
}
]
}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.