Gli eventi personalizzati attivano flussi automatizzati tramite API e passano dati aggiuntivi per la personalizzazione. Ogni evento può includere campi personalizzati, come numeri di tracciamento, dettagli del prodotto o link per le recensioni, da utilizzare nel contenuto del flusso.
Mentre i trigger standard (come Ordine effettuato o Carrello abbandonato) coprono eventi comuni, gli Eventi personalizzati ti permettono di automatizzare azioni uniche come revisione inviata o carta regalo creata che vanno oltre i trigger integrati di Omnisend.
Prima di iniziare
Quando integri il tuo negozio con Omnisend, un insieme di eventi standard diventa disponibile, inclusi Iscritto al Marketing, Ordine Effettuato e Carrello abbandonato. Se vuoi attivare un flusso per un tipo di azione diverso, dovrai utilizzare un Evento Personalizzato.
Gli Eventi Personalizzati possono essere:
Creato manualmente tramite API, o;
Aggiunto automaticamente tramite integrazione con un app di terze parti.
Omnisend supporta e raccomanda di utilizzare solo l'API v5 per gli Eventi Personalizzati. Le versioni precedenti, come la v3, sono ancora funzionanti ma non sono più attivamente supportate.
Se non hai mai lavorato con le API prima, ti consigliamo vivamente di coinvolgere uno sviluppatore per aiutarti a configurare gli Eventi Personalizzati.
La documentazione API spiega come funziona l'integrazione, ma uno sviluppatore è il più attrezzato per implementarla correttamente utilizzando i dettagli tecnici forniti.
Gli eventi personalizzati appaiono nel menu a discesa del trigger del flusso automatizzato dopo che sono stati attivati almeno una volta.
Gli eventi personalizzati richiedono un contatto identificato (email o numero di telefono) per funzionare. I visitatori anonimi restituiranno un errore 400.
⚡ Esempi di Eventi Personalizzati Aggiunti da Strumenti di Terze Parti
AfterShip: Info Ricevuta– Attiva il flusso quando un ordine viene spedito.
Campi personalizzati: numero di tracciamento, URL di tracciamento.
Intercom: Recensione Creata– Attiva il flusso quando un contatto lascia un commento per un agente di supporto.
Campi personalizzati: valutazione, contenuto della recensione.
Growave: Wishlist Di nuovo disponibile– Attiva il flusso quando un articolo della lista dei desideri è di nuovo disponibile.
Campi personalizzati: dettagli del prodotto.
Junip: Recensione Creata– Attiva il flusso quando viene inviata una recensione del prodotto.
Campi personalizzati: informazioni sul prodotto, link per l'invio della recensione.
Crea un Evento Personalizzato
Per far funzionare l'evento personalizzato, dovrai aggiungerlo al tuo account Omnisend e configurarlo sul lato del terzo fornitore.
Passaggio 1. Accedi agli Eventi Personalizzati.
Naviga a Impostazioni Negozio → API → Eventi personalizzati → Clicca Crea evento personalizzato per iniziare.
Passo 2. Imposta tramite la documentazione API.
Verrai reindirizzato alla documentazione API, dove il tuo sviluppatore può completare l'impostazione e creare l'Evento Personalizzato. Qui, devi:
Seleziona v5 come versione di riferimento API;
Naviga a API Eventi → Eventi → Invia evento Cliente.
Passaggio 3. Copia la Chiave API.
Vai a Impostazioni Negozio → API → Crea chiave API e copia la tua Chiave API.
Passo 4. Aggiungi la Chiave API all'intestazione.
Nella documentazione API, seleziona Intestazione e incolla la tua Chiave API nel campo Intestazione.
Passo 5. Completare i Parametri del Corpo.
Segui la procedura guidata per inserire i dettagli richiesti dell'evento:
Contatto – Devi includere almeno un identificatore di contatto: un indirizzo email o numero di telefono di un contatto con cui desideri passare l'evento.
Puoi anche includere dati aggiuntivi come indirizzo, etichette, data di nascita, o proprietà personalizzate. Queste sono memorizzate nel profilo del contatto e persistono nel tempo.
ID evento – Ad esempio,
60ba330da4a60c8ed682c5bd:Nome evento – Ad esempio,
Revisione inviata;Data evento -Facoltativa. Se utilizzata, deve essere una data passata o presente. Le date future causeranno il fallimento dell'evento.
Versione evento - Facoltativa. Può essere lasciata vuota per gli Eventi Personalizzati.
Origine - Questo dovrebbe essere sempre impostato su
"api"Proprietà (opzionale) – Aggiungi eventuali dati aggiuntivi per personalizzare il tuo flusso (vedi la struttura di esempio qui sotto).
Una volta completato, fai clic su Provalo per creare l'evento.
Passo 6. Testa il tuo Evento.
Verifica la creazione dell'evento:
Controlla un codice di stato 200 nella risposta API dopo aver cliccato su "Provalo."
Vai a Impostazioni Negozio → API → Eventi personalizzati per confermare che l'evento appare nella tua lista.
Se riscontri errori, controlla Impostazioni Negozio → API → log API per dettagli.
💡 Attiva un evento di prova:
Usa il POST /events endpoint per attivare manualmente l'evento. Questo lo fa apparire nei trigger del flusso automatizzato.
Note Importanti:
Per modificare un Evento Personalizzato, devi eliminare l'evento esistente e crearne uno nuovo utilizzando la documentazione API.
Disabilitare un Evento Personalizzato ne fermerà il funzionamento, e qualsiasi automazione che lo utilizza come trigger verrà interrotta.
Riattivare un Evento Personalizzato non non riattivare automaticamente il flusso associato. Devi riattivare il flusso automatizzato manualmente.
Eliminare la chiave API creata per l'Evento Personalizzato causerà il fallimento del tuo evento.
Aggiungi Proprietà Evento
Proprietà(anche etichettato come campi personalizzati in Omnisend)passa dati aggiuntivi con ogni evento (ad es., nome del prodotto, URL di tracciamento, valutazione della recensione). Questi dati possono essere utilizzati nei filtri del flusso, nelle condizioni di divisione e nella personalizzazione dei messaggi.
Per aggiungere Proprietà dell'Evento, vai su Proprietà → Oggetto Proprietà. Inserisci il nome della proprietà e il suo valore. Per includere proprietà aggiuntive, clicca su Aggiungi campo, quindi inserisci il nome della prossima proprietà e il suo valore.
Una volta che il tuo evento personalizzato è stato passato a Omnisend, puoi rivedere le proprietà dell'evento sincronizzato andando su Impostazioni Negozio → API → Eventi personalizzati.
Fai clic sul nome dell'evento per visualizzare i campi personalizzati associati.
Nota: Una volta che l'evento personalizzato si sincronizza con Omnisend, le proprietà dell'evento appaiono nell'interfaccia come campi personalizzati. Questi termini si riferiscono agli stessi dati; l'unica differenza è l'etichetta utilizzata, a seconda che tu li stia visualizzando nella documentazione API o all'interno di Omnisend.
Note Importanti:
I nomi delle proprietà sono etichette interne utilizzate per fare riferimento ai dati nelle automazioni e nella Personalizzazione dei messaggi.
I nomi delle proprietà non possono essere cambiati dopo che l'evento è stato creato. Per aggiornare un nome di proprietà, elimina e ricrea l'evento.
I valori delle proprietà possono cambiare nel tempo inviando nuovi eventi con valori aggiornati.
Esempio: Se un contatto lascia una recensione da 1 stella, invia un evento con
reviewType: "1 stella". Se successivamente lo aggiornano a 2 stelle, invia un nuovo evento conreviewType: "2 stelle".
Non puoi passare valori multipli in una singola proprietà (ad esempio,
"1 stella, 2 stelle"). Invia un evento per ogni cambiamento di valore.L'unico tipo di valore supportato per i campi delle proprietà è stringa.
💡 Ti consigliamo di consultare il tuo sviluppatore o il fornitore di integrazione di terze parti per determinare il formato dati corretto per ciascun campo personalizzato.
Usa eventi personalizzati nel flusso automatizzato
Passo 1: Crea un Flusso.
Vai a Automazioni → Crea flusso → Crea da zero.
Nel menu a discesa del trigger, trova il tuo Evento Personalizzato.
Passo 2: Configura le impostazioni del Flusso.
Una volta aggiunto il trigger dell'Evento Personalizzato, tutte le impostazioni del flusso si popolano con i dati dell'evento:
Filtro del trigger – Filtra per valori del campo personalizzato (queste sono le proprietà dell'evento che hai definito tramite API).
Blocco di divisione – Ramifica i flussi di lavoro in base ai campi personalizzati.
Passo 3: Personalizza il Contenuto del Messaggio
Puoi utilizzare i dati dei campi personalizzati per personalizzare il contenuto dei tuoi messaggi, inclusi Email, SMS e Notifiche Push.
Se stai passando un link come proprietà dell'evento, puoi usarlo anche con un pulsante nella tua Email.
Usa il link di disiscrizione nel flusso automatizzato
Quando si utilizza un Evento Personalizzato per attivare un flusso automatizzato, il blocco di contenuto del piè di pagina include un link di disiscrizione per impostazione predefinita.
Ti consigliamo di includere questo link in tutti i messaggi. Tuttavia, non è richiesto se il messaggio è transazionale (ad es., relativo a un ordine effettuato dal cliente).
Importante: Flussi automatizzati attivati da eventi personalizzati invierà messaggi ai contatti non iscritti per impostazione predefinita. Se non vuoi non inviare messaggi ai contatti non iscritti, aggiorna il Impostazioni Canale Flusso facendo clic sul blocco del trigger e regolando le preferenze.
Risoluzione dei problemi
Problema 1: L'evento personalizzato non appare nel menu a discesa del trigger del flusso automatizzato.
Ciò è previsto poiché gli eventi compaiono nella lista dei trigger del flusso automatizzato solo dopo essere stati attivati almeno una volta.
Utilizza l'endpoint POST /events per attivare manualmente l'evento. Questo lo fa apparire nei trigger del flusso automatizzato.
Esempio di chiamata API (v5):
POST https://api.omnisend.com/v5/events
Headers:
X-API-KEY: your-api-key
Content-Type: application/json
Body:
{
"origin": "api",
"email": "[email protected]",
"eventName": "Product Back in Stock",
"fields": {
"productName": "Blue Widget",
"productURL": "https://yourstore.com/products/blue-widget"
}
}
Problema 2: Ricezione di un errore 400 quando si attiva l'evento.
Un errore 400 indica un problema relativo al payload, il che significa che la richiesta inviata a Omnisend non è valida. Questi errori originano dal lato del mittente, non da Omnisend.
Per risolvere questo, vai a Impostazioni Negozio → API → log API e controlla i 400 errori.
💡 Puoi utilizzare il filtro a discesa per visualizzare solo errori di livello 400.
Problema 3: i campi personalizzati di Shopify Flow non appaiono.
Shopify Flow utilizza un endpoint e una struttura JSON diversi rispetto all'API standard di Omnisend, quindi i campi personalizzati potrebbero non apparire come previsto.
Per risolvere questo:
Utilizza la sintassi della variabile di template
##{{}}quando mappi i campi nelle azioni di Shopify Flow.Assicurati che i nomi dei campi corrispondano esattamente a quanto definito in Impostazioni Negozio → API → Eventi personalizzati (sono sensibili al maiuscolo).
Tieni presente: gli eventi di Shopify Flow non appaiono nei log API in Omnisend, poiché questo è un comportamento previsto.
Per istruzioni complete sulla configurazione, fai riferimento all'articolo Integra Shopify Flow con Omnisend.
Problema 4: L'evento funzionava, ora non si attiva.
Se il tuo evento smette improvvisamente di attivarsi:
Vai a Impostazioni Negozio → API → Eventi personalizzati per controllare se l'evento è ancora abilitato.
Se l'evento è stato eliminato, dovrai ricrearlo e aggiornare eventuali flussi di lavoro che lo utilizzano come trigger.
Controlla i log API sotto Impostazioni Negozio → API → log API per errori recenti o richieste non riuscite.
Domande frequenti
Perché la documentazione API li chiama "proprietà dell'evento" ma Omnisend li chiama "campi personalizzati"?
Questa è una differenza di terminologia tra la documentazione API e l'interfaccia di Omnisend. Quando crei proprietà degli eventi nella documentazione API, vengono sincronizzate con Omnisend e vengono visualizzate come campi personalizzati nei flussi automatizzati, nei trigger, nelle suddivisioni e nella personalizzazione dei messaggi. Entrambi i termini si riferiscono agli stessi dati: le informazioni aggiuntive trasmesse con ciascun evento personalizzato.
Qual è la differenza tra le Proprietà Personalizzate del Contatto e le Proprietà dell'Evento?
Le proprietà personalizzate del Contattosono memorizzate nel profilo del contatto e persistono nel tempo. Vengono trasmesse utilizzando il
oggetto customProperties all'interno delblocco dell'oggetto contatto del payload dell'evento. Questi valori sono visibili nel profilo del contatto e possono essere riutilizzati in campagne, automazioni e segmentazione.Le proprietà dell'evento, d'altra parte, vengono trasmesse nel
blocco delle proprietà dell'evento. Sono legate solo all'evento che è stato attivato, etichettato come campi personalizzati, e non persistono nel profilo del contatto. Questi sono utili per condizioni specifiche degli eventi, come filtrare per nome del prodotto, punteggio delle recensioni o totale dell'ordine all'interno dei flussi automatizzati.
Posso modificare i nomi delle proprietà dell'evento dopo aver creato un evento?
No. I nomi delle proprietà non possono essere cambiati una volta che l'evento è stato creato. Se hai bisogno di rinominare una proprietà, dovrai eliminare l'evento esistente e crearne uno nuovo con il nome della proprietà aggiornato.
Nota: Eliminare un evento attivo disabiliterà eventuali flussi di lavoro che lo utilizzano come trigger.
Quale versione API dovrei usare per gli Eventi Personalizzati – v3 o v5?
Usa v5: https://api.omnisend.com/v5/events e includi "origin": "api" nel corpo della tua richiesta.
Sebbene gli eventi creati nell'interfaccia utente siano compatibili sia con v3 che con v5, v5 è lo standard attuale e raccomandato per tutte le nuove implementazioni.
Posso passare URL nelle proprietà dell'evento?
Sì. Gli URL possono essere trasmessi come valori stringa nelle proprietà dell'evento. Possono essere utilizzati nei filtri di flusso automatizzato, nelle condizioni di divisione, nelle regole di segmentazione, o direttamente nel contenuto del messaggio utilizzando variabili di personalizzazione come [[event.referralLink]].
Per ulteriore assistenza con eventi personalizzati, non esitare a contattarci a [email protected] o tramite chat in-app.