Les annotations de graphique vous permettent de marquer des événements importants - déploiements, releases, campagnes marketing, incidents, jalons custom - sur chaque graphique temporel Zenovay. Quand le trafic ou le revenu varie, vous voyez ce qui a changé au même moment sans quitter le tableau de bord.
Pourquoi les annotations comptent
La plupart des questions analytiques se résument à "qu'est-ce qui a changé ?". Une chute inattendue le mardi après-midi est bien plus facile à trier quand vous voyez "deploy: release v2.5" marqué à 14h32. Les annotations transforment le tableau de bord en un seul fil temporel où métriques métier et événements opérationnels coexistent.
Les cinq types d'annotation
| Type | Couleur | Utilisation typique |
|---|---|---|
deploy | Bleu | Déploiements de code, changements d'infra, mises en production de configuration |
release | Émeraude | Annonces publiques de releases, coupes de version |
campaign | Ambre | Campagnes marketing, lancements publicitaires, envois d'e-mails |
incident | Rouge | Incidents impactant les clients, pannes |
custom | Violet | Tout le reste - réunions de direction, intégrations partenaires, audits |
Chaque type a une icône et une couleur distinctes pour identifier d'un coup d'œil ce qui a changé.
Trois façons de créer des annotations
Option 1 - Dans le tableau de bord
Ouvrez le tableau de bord de votre site et sélectionnez l'onglet Analytics, puis cliquez sur l'icône note à n'importe quel point du graphique visiteurs. La boîte de dialogue de détails du jour s'ouvre avec trois onglets : Notes, Annotations et Commits. Dans l'onglet Annotations, choisissez un type (deploy, release, campaign, incident ou custom), tapez un message et ajoutez-le. Le marqueur apparaît immédiatement sur le graphique.
C'est la façon la plus rapide de marquer un événement ponctuel. Pour les déploiements que vous livrez régulièrement, la CLI ci-dessous est plus appropriée.
Option 2 - CLI Zenovay (recommandée pour la CI)
La CLI est la voie canonique pour marquer les déploiements depuis un pipeline CI. Elle gère l'authentification via votre connexion de compte et fonctionne sur macOS, Linux et Windows.
zenovay annotation create --type=deploy --message="release v2.5"
Ajoutez-la comme dernière étape de votre pipeline de déploiement pour
que chaque mise en production se marque automatiquement. La commande
quitte avec un code distinct en cas d'erreur de limite de plan (4)
ou de doublon (5), afin que votre pipeline puisse gérer chaque cas.
Voir le guide d'intégration CLI
pour la référence complète des flags et un exemple GitHub Actions.
Option 3 - API REST
Il y a aussi un point de terminaison /api/annotations que le tableau de
bord lui-même utilise. Il s'authentifie avec votre session de tableau de
bord (la même connexion que vous utilisez dans le navigateur), donc ce
n'est pratique que pour un serveur qui détient déjà une session valide.
Les clés API externes zv_* ne sont pas acceptées sur ce point de
terminaison aujourd'hui, donc pour CI et autres environnements automatisés,
la CLI ci-dessus est le bon outil - elle gère l'authentification pour vous.
Voir la référence API Annotations de graphique
pour la forme complète de la requête et réponse.
Limites de plan et comportement
- Gratuit : 10 annotations par équipe et par mois.
- Pro et au-delà : illimité.
Une annotation du même type et du même message dans les 5 minutes
d'une existante est rejetée pour qu'un pipeline CI mal configuré ne sature
pas la chronologie de doublons. Deux annotations du même type avec des
messages différents (par exemple "checkout cassé" puis "checkout réparé")
sont toutes deux autorisées.
Où apparaissent les annotations
- Sous chaque graphique analytique côté client comme bande de puces colorées. Survolez la puce pour voir le message complet et l'horaire exact.
- Dans le panneau de triage des incidents de conversion comme "changement suspect" quand l'annotation tombe dans une fenêtre de ±2 heures autour du début d'un incident.
- Sur la position de l'icône de notes héritée sur le graphique visiteurs du domaine, si vous utilisez déjà la fonctionnalité existante. Les deux surfaces restent synchronisées automatiquement.
Lire la bande de puces
Chaque puce sous un graphique est codée par couleur selon son type, avec l'icône à gauche. Les cinq couleurs restent cohérentes sur tous les graphiques et toutes les pages : une fois apprises, vous pouvez scanner la bande d'un coup d'œil. Un groupe bleu = déploiements, ambre = campagnes, rouge = incidents. La puce affiche votre message et l'heure de création ; survolez-la pour voir l'horodatage complet.
Confidentialité : les tableaux de bord publics ne montrent JAMAIS d'annotations
Si vous partagez un lien public avec quelqu'un en dehors de votre équipe, les annotations sont masquées. Les messages de déploiement et de release sont destinés à l'équipe qui exploite le site, pas aux visiteurs. Aucun moyen d'exposer publiquement les messages d'annotation.
Schémas courants
Marquer chaque déploiement de production automatiquement : ajoutez la commande CLI comme étape post-déploiement. Aucun travail manuel après le câblage initial.
Marquer un lancement de campagne :
zenovay annotation create --type=campaign --message="Lancement soldes"
au moment du go-live. Lors de l'analyse du lift de trafic plus tard,
le marqueur est déjà sur le graphique.
Marquer un incident connu : postez une annotation incident pour expliquer visiblement la chute. Se marie naturellement avec le triage des incidents de conversion.
Dépannage
- "Annotation limit reached" : limite mensuelle Free atteinte. Passez à Pro pour illimité.
- Erreur HTTP 409 (dédup) : vous essayez de poster une annotation avec le même type et le même message dans les 5 minutes d'une existante. Attendez, changez le message, ou acceptez que le premier marqueur représente déjà l'événement. (La CLI retourne le code de sortie 5 pour ce cas.)
- La bande de puces n'apparaît pas : confirmez qu'au moins une annotation existe pour ce site. Elle reste masquée s'il n'y a rien à afficher.
- La puce est dans la mauvaise langue ou le mauvais thème : le thème suit le thème du tableau de bord ; la langue suit la locale du navigateur. Les deux changent automatiquement.