Vai al contenuto

Funzionalità

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

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:

TipoCaso d’usogoal_value
purchaseOrdini e-commerce, pagamenti una tantumObbligatorio
subscriptionAbbonamenti SaaS, iscrizioni a programmiObbligatorio
leadModuli di contatto, richieste di demoFacoltativo
signupRegistrazioni di accountFacoltativo
bookingAppuntamenti, consulenzeFacoltativo
trialAttivazioni di prove gratuiteFacoltativo
otherEventi di conversione personalizzatiFacoltativo

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

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

OpzioneDescrizione
TotaleSomma di tutti i valori dell’obiettivo (spesa complessiva)
ConteggioNumero di eventi (numero di ordini)
MediaValore medio dell’obiettivo (AOV)
MinimoValore dell’obiettivo più basso
MassimoValore dell’obiettivo più alto

Opzioni di intervallo di tempo

OpzioneDescrizione
In qualsiasi momentoTutti i dati storici
Negli ultimi X giorniFinestra mobile
In intervallo di datePeriodo specifico
Prima della dataLimite storico
Dopo la dataDa 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.completed
  • subscription/started
  • form_submit
  • user-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.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 per la documentazione completa dell’endpoint