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:
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:
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
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:
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.completedsubscription/startedform_submituser-signup
Nota
Gli obiettivi registrati dalla Web Analytics 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:
{
"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.
Note
customEvents.upsertcrea il contatto quando nessun contatto ha quell’email.customEvents.importnon crea contatti- Gli eventi vengono aggiornati solo se
occurred_atè più recente di quello esistente - Per un’eliminazione logica imposta
deleted_at(impostalo anullper 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 per la documentazione completa dell’endpoint
