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

# Eventi personalizzati e obiettivi

> Traccia il comportamento degli utenti e gli obiettivi di conversione per creare segmenti RFM e arricchire la cronologia dei contatti.

## Panoramica

Gli eventi personalizzati registrano le azioni degli utenti provenienti da sistemi esterni (e-commerce, CRM, analytics). Compaiono nella cronologia del contatto, e i loro obiettivi ti permettono di creare segmenti RFM (Recency, Frequency, Monetary).

## Cronologia del contatto

Ogni evento personalizzato crea una voce nella cronologia del contatto, così vedi lo storico completo delle sue interazioni:

![Cronologia del contatto con eventi personalizzati](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

Ogni evento mostra il suo `event_name` come tipo della voce nella cronologia (per esempio "order.completed", "subscription.started"). Il campo `properties` conserva un contesto aggiuntivo, visibile nei dettagli della voce.

## Tipi di obiettivo

I segmenti si basano sugli obiettivi. Ogni evento può tracciare un obiettivo:

| Tipo           | Caso d'uso                               | goal_value   |
| -------------- | ---------------------------------------- | ------------ |
| `purchase`     | Ordini e-commerce, pagamenti una tantum  | Obbligatorio |
| `subscription` | Abbonamenti SaaS, iscrizioni a programmi | Obbligatorio |
| `lead`         | Moduli di contatto, richieste di demo    | Facoltativo  |
| `signup`       | Registrazioni di account                 | Facoltativo  |
| `booking`      | Appuntamenti, consulenze                 | Facoltativo  |
| `trial`        | Attivazioni di prove gratuite            | Facoltativo  |
| `other`        | Eventi di conversione personalizzati     | Facoltativo  |

## Creare segmenti RFM

L'analisi RFM (Recency, Frequency, Monetary) individua i tuoi clienti migliori. Usa il generatore di segmenti con le condizioni **Obiettivo**:

![Generatore di segmenti con un obiettivo degli eventi personalizzati](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### Valore monetario: spesa totale

Seleziona il tipo di obiettivo **Acquisto** e l'aggregazione **totale**, poi imposta un valore minimo per trovare i clienti che spendono di più.

### Frequenza: numero di acquisti

Seleziona il tipo di obiettivo **Acquisto** e l'aggregazione **conteggio**, poi imposta un numero minimo per trovare i clienti abituali.

### Recenza: attività recente

Usa il filtro di intervallo "negli ultimi X giorni" per trovare i clienti con acquisti recenti.

### Esempi di segmenti RFM

- **Clienti VIP**: hanno speso oltre 1000 $ AND 5 ordini o più AND hanno acquistato negli ultimi 60 giorni
- **Alto valore a rischio**: hanno speso oltre 500 $ AND nessun acquisto da 90 giorni
- **Nuovi ad alto potenziale**: primo acquisto superiore a 200 $ negli ultimi 30 giorni

### Opzioni di aggregazione

| Opzione   | Descrizione                                                |
| --------- | ---------------------------------------------------------- |
| Totale    | Somma di tutti i valori dell'obiettivo (spesa complessiva) |
| Conteggio | Numero di eventi (numero di ordini)                        |
| Media     | Valore medio dell'obiettivo (AOV)                          |
| Minimo    | Valore dell'obiettivo più basso                            |
| Massimo   | Valore dell'obiettivo più alto                             |

### Opzioni di intervallo di tempo

| Opzione               | Descrizione           |
| --------------------- | --------------------- |
| In qualsiasi momento  | Tutti i dati storici  |
| Negli ultimi X giorni | Finestra mobile       |
| In intervallo di date | Periodo specifico     |
| Prima della data      | Limite storico        |
| Dopo la data          | Da una data specifica |

## Tracciare gli eventi

### Evento singolo

```bash
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "email": "customer@example.com",
    "event_name": "order.completed",
    "external_id": "order_12345",
    "properties": {
      "items": ["Product A", "Product B"],
      "currency": "USD"
    },
    "goal_type": "purchase",
    "goal_value": 149.99
  }'
```

### Importazione in blocco

Importa fino a 50 eventi alla volta:

```bash
curl -X POST "https://your-instance.com/api/customEvents.import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "events": [
      {
        "email": "user1@example.com",
        "event_name": "order.completed",
        "external_id": "order_001",
        "goal_type": "purchase",
        "goal_value": 99.99
      },
      {
        "email": "user2@example.com",
        "event_name": "order.completed",
        "external_id": "order_002",
        "goal_type": "purchase",
        "goal_value": 249.99
      }
    ]
  }'
```

## Formato del nome dell'evento

I nomi degli eventi devono essere in minuscolo e usare lettere, numeri, punti, trattini bassi, trattini o barre:

- `order.completed`
- `subscription/started`
- `form_submit`
- `user-signup`

> [!NOTE]
>
> Gli obiettivi registrati dalla [Web Analytics](https://www.notifuse.com/it/docs/web-analytics/goals.md) arrivano nella cronologia del contatto con una regola più stretta: solo lettere ASCII, numeri, punti e barre, e tutto il resto (trattini e caratteri accentati compresi) viene sostituito da un trattino basso. Un obiettivo web chiamato `user-signup` arriva come `user_signup`. Se invii lo stesso evento da entrambe le strade, scegli un nome che resti invariato in tutte e due.

## Gestire i rimborsi

Usa un `goal_value` negativo per i rimborsi, così i calcoli dell'LTV restano corretti:

```json
{
  "email": "customer@example.com",
  "event_name": "order.refunded",
  "external_id": "refund_12345",
  "goal_type": "purchase",
  "goal_value": -50.00
}
```

## Permessi

Gli eventi personalizzati non hanno un permesso proprio: dipendono da **Contatti**. Per registrare o importare un evento serve la **scrittura** su Contatti, e per leggerlo serve la **lettura** su Contatti. Concedere la lettura su Contatti dà quindi accesso anche agli eventi registrati sui tuoi contatti e alla cronologia che alimentano. Vedi [Amministratori e API Key](https://www.notifuse.com/it/docs/features/admins-api-keys.md).

## Note

- `customEvents.upsert` crea il contatto quando nessun contatto ha quell'email. `customEvents.import` non crea contatti
- Gli eventi vengono aggiornati solo se `occurred_at` è più recente di quello esistente
- Per un'eliminazione logica imposta `deleted_at` (impostalo a `null` per ripristinare l'evento)
- Solo un evento nuovo (un nuovo `external_id`) avvia le automazioni che partono con il suo nome; dalla versione 44.0 un aggiornamento, un'eliminazione logica o un ripristino non le avviano
- Vedi il [riferimento API](https://www.notifuse.com/docs/api-reference/import-custom-events.md) per la documentazione completa dell'endpoint
