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.
Nota: Utilizza l'ultima versione API supportata per Eventi personalizzati. API v3 e API v5 sono deprecate. Non avviare nuove integrazioni utilizzando nessuna delle due versioni.
Se la tua integrazione personalizzata utilizza la propria chiave API per chiamare API v3 o v5, Omnisend potrebbe mostrare un avviso nel tuo account.Segui le indicazioni per la migrazione per aggiornare la tua integrazione.API v5 verrà disattivata il 30 giugno 2027.
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 desideri attivare un flusso per un diverso tipo di azione, dovrai utilizzare un Evento personalizzato.
Gli Eventi personalizzati possono essere:
Creato manualmente tramite API, oppure
Aggiunto automaticamente tramite integrazione con un app di terze parti.
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 un sviluppatore è il più adatto per implementarla correttamente utilizzando i dettagli tecnici forniti.
Gli eventi personalizzati appaiono nel menu a discesa dei trigger di automazione 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 di lavoro quando un ordine viene spedito.
Campi personalizzati: numero di tracciamento, URL di tracciamento.
Intercom: Revisione creata– Attiva il flusso di lavoro 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 di lavoro quando un elemento della wishlist è di nuovo disponibile.
Campi personalizzati: dettagli del prodotto.
Junip: Revisione 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. Configura 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 l'ultima versione come versione di riferimento API;
Naviga su API Eventi → Eventi → Invia evento cliente.
Passaggio 3. Copia la chiave API.
Vai su 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. Completa 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 un numero di telefono di un contatto che desideri passare con l'evento.
Puoi anche includere dati aggiuntivi come indirizzo, tag, data di nascita o proprietà personalizzate. Questi sono memorizzati nel profilo del contatto e persistono nel tempo.
ID evento Ad esempio,
60ba330da4a60c8ed682c5bd:Nome evento – Ad esempio,
Recensione 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 Eventi personalizzati.
Origine - Questo dovrebbe essere sempre impostato su
"api"Proprietà (facoltativa) 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 su 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 l'endpoint POST /events per attivare manualmente l'evento. Questo lo fa apparire nei trigger di automazione.
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 attivatore verrà interrotta.
Riattivare un Evento Personalizzato non non riattiverà automaticamente il flusso di lavoro associato. Devi riattivare manualmente l'automazione.
Eliminare la chiave API creata per l'Evento Personalizzato causerà il fallimento del tuo evento.
Aggiungi proprietà dell'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, fai clic su Aggiungi campo, quindi inserisci il nome della proprietà successiva e il suo valore.
Una volta che il tuo evento personalizzato è passato a Omnisend, puoi rivedere le proprietà dell'evento sincronizzate 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 riferirsi 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 di 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 su Automazioni Crea flusso Crea da zero.
Nel menu a discesa dell'attivatore, 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 di lavoro 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 – Filtra i flussi di lavoro in base ai campi personalizzati.
Passo 3: Personalizza il contenuto del messaggio
Puoi usare 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 nell'automazione
Quando utilizzi un Evento Personalizzato per attivare un flusso di automazione, 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 esempio, 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 di attivazione e regolando le preferenze.
Risoluzione dei problemi
Problema 1: L'evento personalizzato non appare nel menu a discesa dei trigger di automazione.
Questo è previsto poiché gli eventi appaiono nell'elenco dei trigger di automazione solo dopo essere stati attivati almeno una volta.
Utilizza l'endpoint POST /events per attivare manualmente l'evento. Questo lo fa apparire nei trigger di automazione.
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 provengono dal lato del mittente, non da Omnisend.
Per risolvere questo, vai su Impostazioni Negozio → API → Log API e rivedi gli errori 400.
💡 Puoi usare il filtro a discesa per visualizzare solo gli errori di livello 400.
Problema 3: campi personalizzati di Shopify Flow non visibili.
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:
Usa la sintassi della variabile modello
{{}}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, ma ora non si attiva.
Se il tuo evento smette improvvisamente di attivarsi:
Vai su Impostazioni Negozio API Eventi personalizzati per controllare se l'evento è ancora abilitato.
Se l'evento è stato eliminato, dovrai ricrearlo e aggiornare eventuali flussi che lo utilizzano come attivatore.
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à 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 passate con ciascun evento personalizzato.
Qual è la differenza tra Proprietà personalizzate di Contatto e Proprietà evento?
Proprietà personalizzate di 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 della recensione o totale dell'ordine all'interno dei flussi di automazione.
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 di proprietà aggiornato.
Nota: Eliminare un evento attivo disabiliterà qualsiasi flusso di lavoro che lo utilizza come trigger.
Quale versione dell'API dovrei utilizzare per gli Eventi Personalizzati?
Usa l'ultima versione API supportata mostrata nella documentazione API attuale.API v3 e API v5 sono deprecate.
Posso passare URL nelle proprietà degli eventi?
Sì. Gli URL possono essere trasmessi come valori stringa nelle proprietà dell'evento. Possono essere utilizzati nei filtri di automazione, 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.