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

# Annotazioni

> Segna i momenti che spiegano un grafico: un lancio, una campagna, un disservizio.

![Elenco delle annotazioni che mescola voci manuali e annotazioni automatiche dei broadcast, filtrato per Tutti, Manuale o Broadcast](https://www.notifuse.com/docs/assets/screenshots/web_analytics/annotations.png)

Un'annotazione segna un momento, come il giorno in cui hai rilasciato una novità, la mattina in cui il sito è andato giù o l'ora in cui è partita una campagna. Compare come una linea verticale con un'etichetta sui grafici di Web Analytics, così un picco o un calo hanno la loro spiegazione accanto.

Le annotazioni appartengono al workspace e si gestiscono in **Web Analytics** → **Annotazioni**.

## Aggiungere un'annotazione

Clicca **Aggiungi** e compila il modulo:

| Campo       | Obbligatorio | Note                                                                                                  |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| Data        | Sì           | Il giorno da segnare.                                                                                 |
| Ora         | Sì           | Il valore predefinito è 12:00, di solito abbastanza preciso per un grafico giornaliero.               |
| Fuso orario | Sì           | Parte dal fuso orario in cui sono disegnati i tuoi grafici.                                           |
| Titolo      | Sì           | Fino a 100 caratteri. È il testo che compare sul grafico.                                             |
| Descrizione | No           | Fino a 500 caratteri, mostrata nel tooltip del grafico e nell'elenco.                                 |
| Colore      | No           | Colori predefiniti: verde, rosso, ambra, blu e il viola usato dai broadcast. Blu se non scegli nulla. |

> [!NOTE]
>
> Il fuso orario viene salvato con l'annotazione, quindi il momento si visualizza esattamente come è stato inserito: un disservizio registrato alle 9 a Tokyo resta alle 9 anche per un collega a Parigi.

## Dove compaiono

Sul grafico della **Dashboard** e sul grafico nel pannello di un obiettivo, nella sezione **Obiettivi**.

Ogni annotazione è disegnata come una linea verticale tratteggiata nel suo colore, con il titolo in cima all'area del grafico (troncato se è lungo). Passando il mouse su quel punto del grafico, il titolo e la descrizione dell'annotazione si aggiungono al tooltip, sotto i valori delle metriche.

La linea cade sull'intervallo che contiene il momento, quindi la sua precisione dipende dalla granularità che stai guardando. Le annotazioni fuori dal periodo visualizzato non vengono disegnate.

> [!NOTE]
>
> Più annotazioni che cadono nello stesso intervallo si riducono a una sola linea, etichettata con il primo titolo e un `+N`. Passaci sopra con il mouse e il tooltip le elenca tutte per intero.

## Annotazioni dei broadcast

Quando un broadcast inizia l'invio, Notifuse scrive un'annotazione con il suo nome, contrassegnata come **Broadcast** nell'elenco e disegnata in viola sui grafici, così un aumento del traffico e la campagna che l'ha causato compaiono sullo stesso grafico.

- Viene scritta solo quando l'invio è iniziato, dopo che i controlli su workspace, provider e template sono tutti passati. Un broadcast che non riesce a caricare i suoi template non invia nulla a nessuno e non viene mai annotato.
- C'è un'annotazione per broadcast, per quante volte riprenda il suo processo di invio.
- Sono sempre mostrate sui grafici, e per scelta nessuna impostazione le nasconde.
- In seguito l'annotazione è indipendente dal broadcast: eliminare il broadcast la lascia al suo posto, visto che l'invio è avvenuto davvero, ed eliminare l'annotazione non ha effetto sul broadcast.

Il filtro **Tutti / Manuale / Broadcast** sopra l'elenco filtra solo l'elenco, non i grafici.

## Modificare ed eliminare

Ogni annotazione si può modificare o eliminare dall'elenco, comprese quelle dei broadcast, per esempio per riformulare un titolo automatico in qualcosa che riconoscerai fra sei mesi.

La modifica cambia solo il momento e il suo fuso orario, il testo e il colore. Un'annotazione di broadcast mantiene la sua origine e il suo contrassegno comunque tu la riscriva, e un'annotazione inserita da te non può mai diventare un'annotazione di broadcast.

L'eliminazione è immediata e non si può annullare.

## Gestirle tramite API

Le annotazioni hanno cinque endpoint, documentati nell'[API Reference](https://www.notifuse.com/docs/api-reference.md):

| Endpoint                       | Scopo                                             |
| ------------------------------ | ------------------------------------------------- |
| `GET /api/annotations.list`    | Elenco, filtrabile per `start`, `end` e `sources` |
| `GET /api/annotations.get`     | Recupera un'annotazione per id                    |
| `POST /api/annotations.create` | Crea                                              |
| `POST /api/annotations.update` | Modifica                                          |
| `POST /api/annotations.delete` | Elimina                                           |

L'accesso segue il permesso di Web Analytics: lettura per `list` e `get`, scrittura per il resto.

Collega la tua pipeline di deploy o la tua pagina di stato a questi endpoint, così rilasci e incidenti finiscono sul grafico senza che nessuno debba inserirli.

> [!WARNING]
>
> L'API crea solo annotazioni **manuali** (chi chiama non può crearne una di broadcast), e non esiste una chiave di idempotenza. Un job che ritenta una creazione scrive una seconda annotazione. Elimina i duplicati dal tuo lato, oppure fai pulizia dalla pagina Annotazioni.

## Note

- `list` restituisce per impostazione predefinita le 100 annotazioni più recenti, e al massimo 1.000. La pagina Annotazioni e i grafici chiedono entrambi il massimo.
- La pagina Annotazioni funziona anche prima che il tracker sia installato, a differenza del resto di Web Analytics: un workspace che invia solo broadcast raccoglie comunque le annotazioni dei broadcast.
- [API Reference](https://www.notifuse.com/docs/api-reference.md)
