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

# Obiettivi

> Registra le conversioni del tuo sito web e usale nei segmenti e nelle automazioni.

![Sezione Obiettivi con una scheda per obiettivo che mostra conteggio, tasso di conversione, valore totale e valore mediano rispetto al periodo precedente](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goals.png)

Un obiettivo è qualcosa che vale la pena contare: un'iscrizione, un acquisto, una richiesta di demo. Il tuo sito lo segnala e Web Analytics lo registra sulla visita che l'ha prodotto.

## Registrare un obiettivo

```javascript
NotifuseAnalytics.trackGoal({ action: 'purchase', type: 'purchase', value: 49.9 })
```

| Campo        | Obbligatorio | Note                                                                                                          |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `action`     | Sì           | Il nome dell'obiettivo, fino a 100 byte (100 caratteri ASCII, meno per testo accentato o non latino).         |
| `type`       | Sì           | Il tipo di conversione: `purchase`, `subscription`, `lead`, `signup`, `booking`, `trial` o `other`.           |
| `value`      | No           | Un numero non negativo: il fatturato, o qualunque cosa tu stia sommando.                                      |
| `properties` | No           | Fino a 50 valori tuoi, 1024 byte per valore e 8 KB in totale, chiavi comprese. Vengono salvati come stringhe. |

`type` è obbligatorio perché solo il tuo sito sa se una conversione è una vendita o
un lead, e le condizioni di segmento basate sugli obiettivi filtrano su questo campo.
La promise di `trackGoal` viene rifiutata quando `type` manca o non è uno di questi valori, in minuscolo,
quindi intercetta l'errore se attendi `trackGoal` prima di un reindirizzamento. Usa `other`
quando nessuno degli altri valori è adatto.

Il percorso della pagina corrente e la sua posizione nella visita vengono aggiunti automaticamente, così un obiettivo sa sempre dove è avvenuto.

> [!NOTE]
>
> Gli obiettivi vengono inviati subito, senza attendere il battito successivo, così arriva anche una conversione su una pagina che il visitatore sta per lasciare.

> [!WARNING]
>
> Un `value` negativo rende non valido l'intero obiettivo: l'obiettivo viene scartato, nome compreso, non solo il numero. L'API degli [eventi personalizzati](https://www.notifuse.com/it/docs/features/custom-events.md) si comporta diversamente: accetta di proposito valori negativi, per rimborsi e chargeback.

Non devi dichiarare gli obiettivi da nessuna parte prima di usarli. La scheda Obiettivi elenca i nomi che il tuo sito ha inviato, ordinati per conversioni, e mostra fino ai 30 obiettivi con più conversioni nel periodo e con i filtri che hai applicato.

### Valori da un tag manager o da JavaScript semplice

Uno snippet o un tag manager passa spesso valori letti dalla pagina, quindi `trackGoal` converte per te i tipi più comuni:

- Un `value` passato come stringa scritta come un numero JSON, come `'49.90'` o `'120'`, viene salvato come numero. `'49,90'`, `'1,299.00'`, `'€49.90'` e `'.5'` non lo sono, e un obiettivo di questo tipo viene escluso, come descritto più sotto.
- Un `value` uguale a `NaN` (ciò che restituisce `parseFloat('€49.90')`), un numero infinito, `null` o una stringa vuota registra l'obiettivo senza valore e senza avviso. La scheda Obiettivi e i report contano un obiettivo così come 0 nei valori medi e mediani.
- Numeri e booleani in `properties` vengono salvati come stringhe, e una `Date` come la sua stringa ISO. `null`, `NaN`, un numero infinito e una `Date` non valida vengono salvati come stringa vuota, e una voce `undefined` viene esclusa.
- Quando `properties` è `false`, `''` o `0`, come restituisce `coupon && { coupon }` senza coupon, l'obiettivo viene registrato senza proprietà.

Un obiettivo i cui dati non possono comunque essere registrati viene escluso, con un avviso nella console del browser. La chiamata si risolve comunque, quindi una pagina che attende `trackGoal` prima di reindirizzare reindirizza lo stesso. Questo vale per un `action` mancante, vuoto, non di tipo stringa o oltre i 100 byte, un `value` che non è un numero o è fuori dall'intervallo da 0 a 1e12, e `properties` che sono un array, una stringa non vuota, `true` o un numero diverso da `0` e `NaN`, che contengono un oggetto o un array, o che superano i limiti indicati sopra. Il resto della visita continua a essere registrato.

Un `Map`, un `FormData` o un `URLSearchParams` non ha campi propri, quindi un obiettivo che ne riceve uno come `properties` viene registrato senza proprietà e senza avviso: passa invece `Object.fromEntries(…)`, escludendo i campi file, il cui valore è un oggetto.

## Cosa produce un obiettivo

L'icona a forma di occhio sulla scheda di un obiettivo apre la sua dashboard a tutta larghezza. Ogni dato mostrato conta solo le conversioni di quell'obiettivo.

![Dashboard dell'obiettivo add_to_cart: pulsanti per l'obiettivo precedente e successivo, il periodo confrontato, la striscia Conteggio, Tasso conv., Valore totale e Valore mediano, un grafico giornaliero con annotazioni, una mappa di calore per giorno e ora, e le schede Sorgenti principali, Campagne principali e Dispositivi](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goal_dashboard.png)

- **La barra** torna agli Obiettivi, passa all'obiettivo precedente o successivo della griglia con le frecce o con **K** e **J**, e mostra il periodo e quello con cui viene confrontato. Entrambi si impostano nella scheda Obiettivi.
- **Filtrato per** elenca i filtri applicati, ognuno rimovibile. Sono i filtri dell'intera sezione Web Analytics: cliccando una riga o un paese nella dashboard ne aggiungi uno anche lì.
- **La striscia dei KPI** mostra Conteggio, Tasso conv., Valore totale e Valore mediano, rispetto al periodo di confronto. Cliccando Conteggio, Valore totale o Valore mediano ne visualizzi il grafico.
- **Tasso conv.** è il numero di conversioni dell'obiettivo diviso per le sessioni del periodo, come sulla scheda dell'obiettivo. Conta gli eventi obiettivo, non le sessioni che convertono, quindi un obiettivo raggiunto due volte in una sessione conta due volte e il tasso può superare il 100%. Il suo tooltip avverte che include tutto il traffico, qualunque fosse lo scopo del visitatore.
- **Il grafico** segue la granularità che scegli e riporta le tue [annotazioni](https://www.notifuse.com/it/docs/web-analytics/annotations.md), accanto a una mappa di calore dell'obiettivo per giorno e ora.
- **Le schede** suddividono le conversioni e il loro valore: Sorgenti principali (referrer, canali, gruppi di canali), Campagne principali (campagne, sorgenti, medium, escluse le conversioni senza campagna), Dispositivi (dispositivi, browser, sistemi operativi), Paesi (mappa e lista), Pagine di atterraggio (pagine di atterraggio e pagine obiettivo), e una scheda per le dimensioni personalizzate che hanno un nome.

Nei report, gli obiettivi forniscono le misure Goals, Total Goal Value, Avg Goal Value, Median Goal Value e Converting Sessions, e le dimensioni Goal Name, Goal Path e Goal Value. A livello di sessione, Sessions with Goals e Goal Value ti permettono di confrontare i canali per conversioni invece che per traffico.

Per un visitatore **identificato**, un obiettivo diventa anche un evento personalizzato sulla timeline del suo contatto, e quindi è utilizzabile da segmenti e automazioni. Vedi [Identificare i visitatori](https://www.notifuse.com/it/docs/web-analytics/identifying-visitors.md).

## Nomi degli obiettivi sulla timeline del contatto

Un obiettivo che arriva sulla timeline di un contatto viene prima normalizzato: convertito in minuscolo, con tutto ciò che non è ASCII `a–z`, `0–9`, `.` e `/` ridotto a un singolo `_`, i `_` iniziali e finali rimossi, e il risultato troncato a 100 caratteri. Così `Trial Started` arriva come `trial_started`, ed è su quel nome che un'automazione o un segmento fa la corrispondenza.

> [!WARNING]
>
> L'insieme dei caratteri conservati è solo ASCII, quindi le lettere accentate e non latine vengono eliminate invece di essere traslitterate: `Café` arriva come `caf`. Un nome senza alcuna lettera o cifra ASCII, come `購入`, si normalizza in una stringa vuota e non arriva mai sulla timeline. L'obiettivo viene comunque registrato e compare nei report: viene saltata solo la copia sulla timeline. Usa nomi di obiettivo ASCII se ci basi segmenti o automazioni.
>
> Questa regola è anche più restrittiva di quella per i nomi degli eventi inviati tramite l'API degli [eventi personalizzati](https://www.notifuse.com/it/docs/features/custom-events.md), che accetta i trattini: `black-friday` inviato da un obiettivo web diventa `black_friday`.

## Usare gli obiettivi web nei segmenti

Un obiettivo web porta le stesse tre informazioni di un evento personalizzato creato
tramite l'API: un nome, un valore e un tipo.

- La condizione **Obiettivo** degli eventi personalizzati trova gli obiettivi web, di un tipo
  specifico o con **Qualsiasi obiettivo**, e ne conta, somma e calcola la media del valore.
- Un'**automazione** può attivarsi su un evento personalizzato con il nome normalizzato dell'obiettivo.

> [!NOTE]
>
> Il tipo viene dichiarato dal tuo sito, non verificato da Notifuse, e la stessa pagina
> sceglie anche il nome e il valore dell'obiettivo. Tienine conto quando leggi i report sul
> fatturato, come faresti per gli eventi inviati tramite l'API.

## Limiti

- Per ogni batch di scrittura, fino a 100 obiettivi di una sessione vengono riportati sulla timeline del contatto. Gli obiettivi oltre questa soglia nello stesso batch vengono esclusi dalla timeline in modo definitivo, e il contatore riparte a ogni batch, quindi una visita lunga che continua a convertire può arrivare in totale a più di 100 voci sulla timeline. La visita continua a essere registrata: il limite riguarda solo la copia sulla timeline.
- Un obiettivo più vecchio di 24 ore non viene riportato su una timeline. Un visitatore il cui browser è rimasto offline per un giorno torna con la visita intatta, senza attivare con un giorno di ritardo automazioni del tipo "hai appena fatto questo".
- Un obiettivo con un valore superiore a 1e12, un nome oltre i 100 byte, proprietà con più di 50 chiavi, più di 1024 byte in un valore o più di 8 KB in tutto con le chiavi, una proprietà che contiene un oggetto o un array, o un carattere NUL (`\u0000`) nel nome o nelle proprietà viene scartato: solo l'obiettivo, mai il resto della visita.

## Note

- Gli obiettivi dei visitatori anonimi vengono registrati e riportati normalmente. Solo la copia sulla timeline richiede un'identità.
- Gli eventi riportati sulla timeline contengono il contesto della visita come proprietà (ID della sessione, percorso, percorso di atterraggio, UTM source / medium / campaign, dispositivo e paese) accanto alle tue. Queste chiavi sono impostate da Notifuse e sovrascrivono le proprietà con lo stesso nome.
- Una valuta, un ID ordine o qualsiasi altra informazione legata alla conversione va in `properties`, che vengono inviate e salvate. Non esiste un campo `currency` dedicato: `goal_value` è un semplice numero, quindi se registri più valute, raggruppa i report per la proprietà della valuta invece di sommare i valori tra valute diverse.
- [Riferimento API](https://www.notifuse.com/docs/api-reference.md)
