> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotations

> Marquer les moments qui expliquent un graphique : un lancement, une campagne, une panne.

![Liste des annotations mêlant des entrées manuelles et des annotations automatiques de newsletters, filtrée par Tout, Manuel ou Newsletter](https://www.notifuse.com/docs/assets/screenshots/web_analytics/annotations.png)

Une annotation marque un moment : le jour d'une mise en production, le matin où le site est tombé, l'heure d'envoi d'une campagne. Elle apparaît sous forme de ligne verticale avec un libellé sur vos graphiques d'analyse web, si bien qu'un pic ou un creux a son explication juste à côté.

Les annotations appartiennent à l'espace de travail et se gèrent dans **Analyse web** → **Annotations**.

## Ajouter une annotation

Cliquez sur **Ajouter** et remplissez le formulaire :

| Champ          | Obligatoire | Remarques                                                                                                       |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| Date           | Oui         | Le jour à marquer.                                                                                              |
| Heure          | Oui         | 12:00 par défaut, ce qui suffit en général pour un graphique par jour.                                          |
| Fuseau horaire | Oui         | Prend d'abord le fuseau horaire dans lequel vos graphiques sont tracés.                                         |
| Titre          | Oui         | 100 caractères au maximum. C'est ce qui s'affiche sur le graphique.                                             |
| Description    | Non         | 500 caractères au maximum, affichée dans l'infobulle du graphique et dans la liste.                             |
| Couleur        | Non         | Couleurs prédéfinies : vert, rouge, ambre, bleu, et le violet des newsletters. Bleu si vous ne choisissez rien. |

> [!NOTE]
>
> Le fuseau horaire est enregistré avec l'annotation : le moment s'affiche donc exactement tel qu'il a été saisi. Une panne saisie à 9 h à Tokyo reste affichée à 9 h pour un collègue à Paris.

## Où elles apparaissent

Sur le graphique du **Dashboard**, et sur le graphique du panneau d'un objectif dans la section **Objectifs**.

Chaque annotation est tracée en ligne verticale pointillée de sa couleur, avec son titre en haut de la zone du graphique (tronqué s'il est long). Survoler ce point du graphique ajoute le titre et la description de l'annotation à l'infobulle, sous les valeurs des métriques.

La ligne tombe sur l'intervalle qui contient le moment : sa précision dépend donc de la granularité affichée. Les annotations hors de la période affichée ne sont pas tracées.

> [!NOTE]
>
> Plusieurs annotations qui tombent dans le même intervalle se regroupent en une seule ligne, avec le premier titre suivi de `+N`. Survolez-la : l'infobulle les liste toutes en entier.

## Annotations de newsletters

Quand une newsletter commence à partir, Notifuse écrit une annotation à son nom, étiquetée **Newsletter** dans la liste et tracée en violet sur les graphiques. Une hausse de trafic et la campagne qui l'a provoquée apparaissent ainsi sur le même graphique.

- L'annotation n'est écrite qu'au début de l'envoi, une fois passés les contrôles de l'espace de travail, du fournisseur et des modèles. Une newsletter dont les modèles ne se chargent pas n'envoie rien à personne et n'est jamais annotée.
- Une seule annotation par newsletter, quel que soit le nombre de reprises de sa tâche d'envoi.
- Elles sont toujours affichées sur les graphiques, et aucun réglage ne les masque : c'est voulu.
- L'annotation devient ensuite indépendante de la newsletter : supprimer la newsletter la laisse en place, puisque l'envoi a bien eu lieu, et supprimer l'annotation n'a aucun effet sur la newsletter.

Le filtre **Tout / Manuel / Newsletter** au-dessus de la liste ne filtre que cette liste, pas les graphiques.

## Modifier et supprimer

Toutes les annotations peuvent être modifiées ou supprimées depuis la liste, y compris celles des newsletters, par exemple pour reformuler un titre automatique en quelque chose que vous reconnaîtrez dans six mois.

La modification ne porte que sur le moment et son fuseau horaire, le texte et la couleur. Une annotation de newsletter garde son origine et son étiquette quelle que soit la réécriture, et une annotation saisie à la main ne peut jamais devenir une annotation de newsletter.

La suppression est immédiate et définitive.

## Les gérer par l'API

Les annotations ont cinq endpoints, documentés dans la [référence de l'API](https://www.notifuse.com/docs/api-reference.md) :

| Endpoint                       | Rôle                                                              |
| ------------------------------ | ----------------------------------------------------------------- |
| `GET /api/annotations.list`    | Lister, avec un filtre facultatif sur `start`, `end` et `sources` |
| `GET /api/annotations.get`     | Récupérer une annotation par son id                               |
| `POST /api/annotations.create` | Créer                                                             |
| `POST /api/annotations.update` | Modifier                                                          |
| `POST /api/annotations.delete` | Supprimer                                                         |

L'accès suit la permission Analyse web : lecture pour `list` et `get`, écriture pour les autres.

Branchez votre pipeline de déploiement ou votre page de statut sur ces endpoints : les mises en production et les incidents arrivent sur le graphique sans que personne n'ait à les saisir.

> [!WARNING]
>
> L'API ne crée que des annotations de type **Manuel** (un appel ne peut pas créer d'annotation de newsletter), et il n'y a pas de clé d'idempotence. Une tâche qui retente une création écrit une seconde annotation. Dédupliquez de votre côté, ou faites le ménage depuis la page Annotations.

## Remarques

- `list` renvoie par défaut les 100 annotations les plus récentes, et 1 000 au maximum. La page Annotations et les graphiques demandent tous deux le maximum.
- Contrairement au reste de l'analyse web, la page Annotations fonctionne avant même l'installation du traqueur : un espace de travail qui ne fait qu'envoyer des newsletters accumule quand même des annotations de newsletters.
- [Référence de l'API](https://www.notifuse.com/docs/api-reference.md)
