Sommario
Prima di poter applicare una transazione cliente a una sfida fedeltà, è necessario che il formato Adobe Loyalty Event comprenda il servizio di verifica. Gli eventi dei clienti, provenienti da un sistema POS, un’app mobile, una piattaforma di e-commerce o qualsiasi altra origine, in genere utilizzano lo schema dati del cliente. I trasformatori di eventi colmano questo gap senza richiedere alcuna modifica al sistema a monte.
Panoramica
Una Definizione evento indica alla piattaforma due cose:
- Quali eventi rivendicare — come riconoscere che un evento in ingresso appartiene a questa definizione (corrispondenza)
- Come modificarne la forma — un’espressione JSONata che mappa i campi del cliente nel formato dell’evento fedeltà (trasformazione)
È possibile configurare più definizioni di evento per organizzazione. La piattaforma li valuta in ordine e applica il primo corrispondente. Gli eventi che non corrispondono ad alcuna definizione passano all’acquisizione nativa (vedi Fallback — Native Loyalty Events).
Formato dell’evento fedeltà di Adobe
Ogni definizione di evento deve produrre un oggetto JSON nel formato seguente. Questo è l’input elaborato dal servizio di verifica.
{
"_id": "string — optional; used for duplicate detection if enabled",
"event_name": "string — used for internal metrics and reporting only (e.g. 'purchase', 'visit')",
"timestamp": "ISO 8601 date-time string — when the event occurred",
"utc_offset": "string — UTC offset of the store or device (e.g. '-07:00'); required for daypart matching",
"location_id": "string — optional; store or location identifier",
"transaction_id": "string — optional; dedup key for the transaction",
"loyalty_identity": {
"id": "string — the member's loyalty ID"
},
"item_list": [
{
"item_set": ["string", "..."], // one or more identifiers — SKU, category, event code, etc.
"item_name": "string — optional human-readable label",
"quantity": 1, // integer; how many units
"unit_price": 4.99, // float; price per unit
"sub_total": 4.99 // float; line total (quantity × unit_price)
}
]
}
Note campo
loyalty_identityid, l’ID fedeltà del membro.item_listitem_settimestamputc_offset_idsub_totalCampi definizione evento
guidname"Starbucks POS Purchase".xdmSchemaIdtransformerCome funziona la corrispondenza
Gli eventi in arrivo tramite il servizio core di raccolta dati (DCCS, Data Collection Core Service) contengono un riferimento allo schema XDM nella busta. La piattaforma legge l’ID schema da /body/xdmMeta/schemaRef/id e lo confronta con il xdmSchemaId di ogni definizione.
La piattaforma esamina le definizioni degli eventi dell’organizzazione in ordine e applica la prima corrispondenza. Una volta trovata una corrispondenza, il corpo xdmEntity viene passato al trasformatore.
Scrittura del trasformatore
Il campo transformer è un’espressione JSONata. Riceve l’evento in ingresso JSON come input e deve restituire un oggetto Adobe Loyalty Event valido.
Mappa ogni campo di primo livello del formato di destinazione al percorso corrispondente nell’evento sorgente:
| code language-jsonata |
|---|
|
Se tutti gli eventi che corrispondono a questa definizione rappresentano la stessa attività logica, utilizzare il codice hardware event_name:
| code language-jsonata |
|---|
|
event_name viene utilizzato per le metriche interne e il reporting. Non viene utilizzato come filtro attività. La qualifica dell’attività è determinata dal contenuto item_set, non dal nome dell’evento.
Per gli eventi in arrivo tramite la route DCCS, l’identità del membro viene in genere inclusa nel campo XDM identityMap standard anziché in una proprietà tenant personalizzata. identityMap è una mappa basata sullo spazio dei nomi. La chiave stessa è il nome dello spazio dei nomi e il valore è una matrice di oggetti identità.
| code language-jsonata |
|---|
|
-
Sostituzione dello spazio dei nomi: Sostituisci
Emailcon qualsiasi spazio dei nomi utilizzato dall’organizzazione per i membri fedeltà:Loyalty,ECID,CRMID, ecc. Leggi sempre dallo spazio dei nomi che contiene l’identità del profilo fedeltà principale. -
Usa sempre
[0]:identityMap.Emailè un array. Senza l’indice, JSONata restituisce una sequenza anziché un singolo valore se sono presenti più identità eloyalty_identity.iddiventa un elenco. Aggiungerlo al primo elemento con[0]. -
Evitare i campi tenant personalizzati per l’identità: I gruppi di campi personalizzati a volte espongono un campo di aspetto e-mail (ad esempio
_yourtenant.identification.core.email). Nei dati di esempio questo restituisce un valore e sembra corretto, ma negli eventi di produzione è spesso vuoto. L’origine affidabile dell’identità è sempreidentityMap.
item_setitem_set è una matrice di identificatori di stringa. Includi tutti i campi in base ai quali le attività di verifica potrebbero filtrare:
| code language-jsonata |
|---|
|
Per gli eventi non transazionali (check-in, completamento di un sondaggio, trigger personalizzato) è sufficiente un singolo identificatore:
| code language-jsonata |
|---|
|
unit_priceunit_price deve essere un prezzo unitario. Alcuni schemi di origine memorizzano invece un totale riga (prezzo × quantità). Se il campo di origine è un totale riga, dividere per quantità per ottenere il prezzo unitario:
| code language-jsonata |
|---|
|
Dividi solo se il campo di origine è un totale riga. Se memorizza già un prezzo per unità, eseguirne la mappatura diretta. Se si divide un prezzo per unità per quantità, si otterrà automaticamente un valore errato.
transaction_idSe l’evento di origine non include un identificatore di transazione, puoi derivarne uno stabile dalla marca temporale:
| code language-jsonata |
|---|
|
Questo converte la marca temporale ISO in millisecondi epoca e produce un valore deterministico per un dato evento. Utilizza la funzione di generazione ID della tua piattaforma, se disponibile.
È disponibile la libreria completa delle funzioni JSONata. Esempi utili:
| code language-jsonata |
|---|
|
Esempi
Scenario: un’app mobile invia un evento di archiviazione. Non ci sono elementi di riga — l’evento stesso è l’attività qualificata.
Evento in ingresso:
| code language-json |
|---|
|
Definizione evento:
| code language-json |
|---|
|
Trasformatore formattato (per la leggibilità):
| code language-jsonata |
|---|
|
Evento Adobe Loyalty Di Output:
| code language-json |
|---|
|
Un’attività di verifica senza restrizioni di inclusione/esclusione conterà questo evento come visita qualificata. La singola item_set voce ["store-checkin"] corrisponde a qualsiasi attività che consente tutti gli elementi.
Scenario: un sistema POS invia un payload di transazione. Ogni voce ha uno SKU e appartiene a una categoria. Le attività di verifica utilizzano SKU e categoria per determinare ciò che è idoneo.
Evento in ingresso:
| code language-json |
|---|
|
Definizione evento:
| code language-json |
|---|
|
Trasformatore formattato:
| code language-jsonata |
|---|
|
Evento Adobe Loyalty Di Output:
| code language-json |
|---|
|
Un’attività di verifica con include: ["BEVERAGE"] potrebbe rendere idoneo l’elemento della riga di caffè (il relativo item_set contiene "BEVERAGE") e accumulare 9,00 $ di spesa per tale attività. La riga muffin verrebbe esclusa.
Scenario: gli eventi passano attraverso Adobe Journey Optimizer. L’evento in arrivo è un Experience Event XDM con un ID schema noto. La piattaforma utilizza l’ID dello schema per la corrispondenza anziché un controllo percorso/valore.
Corpo entità XDM in ingresso (il xdmEntity estratto dall’evento AJO):
| code language-json |
|---|
|
Definizione evento:
| code language-json |
|---|
|
Trasformatore formattato:
| code language-jsonata |
|---|
|
Nota: quando un evento corrisponde per ID schema XDM, il trasformatore riceve solo la porzione
xdmEntitydell’evento, non la busta esterna di AJO. Tutti i percorsi nell’espressione del trasformatore sono relativi al corpo dell’entità XDM.
Aggiunta della convalida dello schema JSON (facoltativo)
Se si desidera che la piattaforma convalidi la struttura degli eventi in arrivo prima di tentare la trasformazione, impostare il campo schema su un documento Schema JSON codificato come stringa JSON.
Gli eventi che non superano la convalida dello schema vengono rifiutati prima dell’esecuzione della trasformazione. La risposta all’errore include un errore di convalida specifico che semplifica la diagnosi di eventi a monte con formato non corretto.
| code language-json |
|---|
|
Passa questo schema come stringa JSON minimizzata nel campo schema della definizione dell’evento.
Fallback: eventi fedeltà nativi
Se nessuna definizione di evento corrisponde a un evento in arrivo, la piattaforma tenta di acquisirlo direttamente come evento fedeltà nativo di Adobe. Se il payload è già conforme al formato dell’evento fedeltà descritto in precedenza, non è necessario alcun trasformatore e l’evento viene applicato così com’è. Questo consente ai clienti che hanno preformattato i loro eventi di ignorare completamente la trasformazione.
Riferimento API
Tutte le operazioni di definizione degli eventi utilizzano il percorso di base /loyalty/metadata/config/events.
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
Convalida del trasformatore
Le espressioni JSONata vengono convalidate per la sintassi al momento del salvataggio della definizione dell’evento. Se l’espressione non è valida, l’API restituisce un errore 422 con una descrizione dell’errore di analisi.
Per eseguire il test di un trasformatore prima della distribuzione, utilizzare l’JSONata Exerciser — incollare l’evento di origine come input e l’espressione del trasformatore per verificare che l’output corrisponda al formato dell’evento fedeltà previsto.
Insidie comuni
Questi errori vengono tutti eseguiti senza errori su un semplice payload di test a elemento singolo, che è esattamente il motivo per cui non vengono rilevati. Prima dell’implementazione, verifica sempre il trasformatore rispetto a un payload con due o più prodotti.
L’errore più frequente. Se si utilizza un valore letterale di oggetto singolo con productListItems.SKU, ogni SKU e ogni quantità viene estratta in sequenze di dati raggruppati anziché produrre un elemento riga per prodotto.
✗comprime tutti gli elementi in uno:
| code language-jsonata |
|---|
|
Con due prodotti, item_set contiene entrambi gli SKU e quantity diventa un array come [1, 4].
✓Un elemento riga per prodotto:
| code language-jsonata |
|---|
|
La mappa .{ } viene eseguita una volta per prodotto, in modo che ogni voce diventi la propria.
identityMap.Email è un array. Senza [0], se un profilo contiene più di un’identità nello spazio dei nomi, id diventa un elenco di valori invece di una singola stringa.
✗ identityMap.Email.id
✓ identityMap.Email[0].id
_yourtenant.identification.core.email. Nei dati di esempio restituisce un valore e sembra corretto, ma negli eventi di produzione è spesso vuoto, causando la visualizzazione di loyalty_identity.id null. Utilizza sempre identityMap come origine dell’identità.item_setL’aggiunta di un campo categoria a item_set è semplice, ma se productCategories è di per sé un array, il risultato si espande in modo imprevedibile.
✗Può produrre più voci del previsto:
| code language-jsonata |
|---|
|
Un prodotto con tre categorie produce un item_set con quattro valori.
✓Indicizzare la matrice nidificata per ottenere esattamente un valore:
| code language-jsonata |
|---|
|
item_list è vuoto o mancanteUn evento con item_list vuoto o assente è stato rifiutato in quanto non valido. Per gli eventi non transazionali (check-in, trigger personalizzati) non ci sono elementi di riga naturali, quindi creane uno sintetico:
| code language-jsonata |
|---|
|
timestamp come numero intero dell'epoca Unix invece di ISO 8601La piattaforma richiede una stringa ISO 8601. Se l’evento sorgente è rimasto in millisecondi dall’epoca, convertiscilo:
| code language-jsonata |
|---|
|
utc_offset omessoutc_offset, verranno ignorati sia la corrispondenza della finestra di Fasce orarie che il conteggio delle sequenze di giorni consecutivi. Mappa l’offset UTC dello store o del dispositivo dall’evento di origine ovunque sia disponibile.xdmEntity, non l’envelope esterno di AJO. Tutti i percorsi devono essere relativi alla radice dell’entità XDM. Se l’espressione fa riferimento a campi che si trovano nella busta esterna (ad esempio /body/xdmMeta/...), non verranno trovati e produrranno automaticamente null.