Auf dieser Seite Sie, wie Ereigniszuordnungen eingehende Ereignisse identifizieren und mithilfe von JSONata-Ausdrücken in das Adobe-Treueereignisformat umwandeln, einschließlich Feldanforderungen, übereinstimmendem Verhalten, Beispielen und API-Vorgängen.
Bevor eine Kundentransaktion auf eine Herausforderung bezüglich des Treueprogramms angewendet werden kann, muss sie im Adobe-Treueereignis-Format erfolgen, das der Challenge-Service versteht. Kundenereignisse - aus einem POS-System, einer mobilen App, einer E-Commerce-Plattform oder einer anderen Quelle - verwenden in der Regel das eigene Datenschema des Kunden. Ereignistransformatoren schließen diese Lücke, ohne dass Änderungen am vorgelagerten System erforderlich sind.
Überblick
Eine Ereigniszuordnung teilt der Plattform zwei Dinge mit:
- Welche Ereignisse zu beanspruchen - wie erkennt man, dass ein eingehendes Ereignis zu dieser Definition gehört (Abgleich)
- So formen Sie sie um - ein JSONata-Ausdruck, der die Felder des Kunden dem Treueereignisformat (Transformation) zuordnet
Pro Organisation können mehrere Ereigniszuordnungen konfiguriert werden. Die Plattform bewertet sie der Reihe nach und wendet das erste an, das übereinstimmt. Ereignisse, die keiner Zuordnung entsprechen, fallen in die native Aufnahme (siehe Fallback - native Treueereignisse).
Das Adobe-Treueprogramm-Ereignisformat
Jede Ereigniszuordnung muss ein JSON-Objekt im folgenden Format erzeugen. Dies ist der Input, den der Challenge Service verarbeitet.
{
"_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)
}
]
}
Hinweise zu Feldern
loyalty_identityid enthalten - die Treueprogramm-ID des Mitglieds.item_listitem_settimestamputc_offset_idsub_totalFelder für die Ereigniszuordnung
guidname"Starbucks POS Purchase".xdmSchemaIdtransformerFunktionsweise von Übereinstimmungen
Ereignisse, die über den Data Collection Core Service (DCCS) eingehen, enthalten eine XDM-Schemareferenz in ihrem Umschlag. Die Plattform liest die Schema-ID aus /body/xdmMeta/schemaRef/id und vergleicht sie mit den xdmSchemaId jeder Definition.
Die Plattform führt die Ereigniszuordnungen der Organisation der Reihe nach und wendet die erste Übereinstimmung an. Sobald eine Übereinstimmung gefunden wurde, wird der xdmEntity an den Transformator übergeben.
Schreiben des Transformators
Das transformer ist ein JSONata-Ausdruck. Er empfängt die eingehende Ereignis-JSON als Eingabe und muss ein gültiges Adobe-Treueereignis-Objekt zurückgeben.
Ordnen Sie jedes Feld der obersten Ebene des Zielformats dem entsprechenden Pfad in Ihrem Quellereignis zu:
| code language-jsonata |
|---|
|
Wenn alle Ereignisse, die dieser Definition entsprechen, dieselbe logische Aktivität darstellen, hartcodieren Sie die event_name:
| code language-jsonata |
|---|
|
event_name wird für interne Metriken und Berichte verwendet. Sie wird nicht als Aufgabenfilter verwendet - die Aufgabenqualifizierung wird durch item_set Inhalte bestimmt, nicht durch den Ereignisnamen.
Bei Ereignissen, die über die DCCS-Route eingehen, wird die Identität des Mitglieds normalerweise im standardmäßigen XDM-identityMap statt in einer benutzerdefinierten Mandanteneigenschaft übermittelt. identityMap ist eine vom Namespace verschlüsselte Zuordnung - der Schlüssel selbst ist der Namespace-Name, und der Wert ist ein Array von Identitätsobjekten.
| code language-jsonata |
|---|
|
-
Namespace-Ersetzung: Ersetzen Sie
Emaildurch den Namespace, den Ihre Organisation für Mitglieder des Treueprogramms verwendet -Loyalty,ECID,CRMIDusw. Lesen Sie immer aus dem Namespace, der die primäre Identität des Treueprofils enthält. -
Verwenden Sie immer
[0]:identityMap.Emailist ein Array. Ohne den Index gibt JSONata eine Sequenz anstelle eines einzelnen Werts zurück, wenn mehr als eine Identität vorhanden ist undloyalty_identity.idzu einer Liste wird. An das erste Element mit[0]heften. -
Benutzerdefinierte Mandantenfelder für die Identität vermeiden Benutzerdefinierte Feldergruppen stellen manchmal ein E-Mail-ähnliches Feld bereit (z. B.
_yourtenant.identification.core.email). In Beispieldaten gibt dies einen Wert zurück und sieht korrekt aus, in Produktionsereignissen ist es jedoch häufig leer. Die zuverlässige Identitätsquelle ist immeridentityMap.
item_setitem_set ist ein Array von Zeichenfolgenkennungen. Schließen Sie alle Felder ein, nach denen Ihre Challenge-Aufgaben möglicherweise filtern:
| code language-jsonata |
|---|
|
Bei Ereignissen, die keine Transaktionen sind (ein Check-in, ein Umfrageabschluss, ein benutzerdefinierter Trigger), reicht eine einzelne Kennung aus:
| code language-jsonata |
|---|
|
unit_priceunit_price sollte ein Preis pro Einheit sein. Einige Quellschemata speichern stattdessen eine Zeilensumme (Preis × Menge). Wenn Ihr Quellfeld eine Positionssumme ist, dividieren Sie durch die Menge, um den Stückpreis zu erhalten:
| code language-jsonata |
|---|
|
Nur teilen, wenn das Quellfeld eine Zeilensumme ist. Wenn er bereits einen Preis pro Einheit speichert, mappen Sie ihn direkt — durch Division eines Einheitspreises durch die Menge wird im Hintergrund ein falscher Wert erzeugt.
transaction_idWenn Ihr Quellereignis keine Transaktionskennung enthält, können Sie eine stabile aus dem Zeitstempel ableiten:
| code language-jsonata |
|---|
|
Dies konvertiert den ISO-Zeitstempel in Epochenmillisekunden und erzeugt einen deterministischen Wert für ein bestimmtes Ereignis. Verwenden Sie die ID-Generierungsfunktion Ihrer Plattform, falls verfügbar.
Die vollständige Bibliothek mit JSONata-Funktionen ist verfügbar. Nützliche Beispiele
| code language-jsonata |
|---|
|
Beispiele
Szenario: Eine Mobile App sendet ein Eincheckereignis. Es gibt keine Zeileneinträge - das Ereignis selbst ist die qualifizierende Aktivität.
Eingehendes Ereignis:
| code language-json |
|---|
|
Ereigniszuordnung:
| code language-json |
|---|
|
Formatierter Transformator (zur besseren Lesbarkeit):
| code language-jsonata |
|---|
|
Ausgabe Adobe-Treueereignis:
| code language-json |
|---|
|
Eine Challenge-Aufgabe ohne Ein-/Ausschlussbeschränkungen zählt dieses Ereignis als qualifizierten Besuch. Der einzelne item_set-Eintrag entspricht ["store-checkin"] Aufgabe, die alle Elemente zulässt.
Szenario: Ein Point-of-Sale-System sendet eine Transaktions-Payload. Jeder Zeileneintrag hat eine SKU und gehört zu einer Kategorie. Challenge-Aufgaben verwenden SKU und Kategorie, um zu bestimmen, was qualifiziert ist.
Eingehendes Ereignis:
| code language-json |
|---|
|
Ereigniszuordnung:
| code language-json |
|---|
|
formatierter Transformator:
| code language-jsonata |
|---|
|
Ausgabe Adobe-Treueereignis:
| code language-json |
|---|
|
Bei einer Challenge-Aufgabe mit include: ["BEVERAGE"] würde der Kaffeezeileneintrag qualifiziert (sein item_set enthält "BEVERAGE") und für diese Aufgabe 9,00 USD an Ausgaben angesammelt. Der Zeileneintrag Muffin würde ausgeschlossen.
Szenario: Ereignisse fließen durch Adobe Journey Optimizer. Das eingehende Ereignis ist ein XDM-Erlebnisereignis mit einer bekannten Schema-ID. Die Plattform verwendet die Schema-ID für die Zuordnung anstelle einer Pfad-/Wertprüfung.
Eingehender XDM-Entitätstext (der aus dem AJO-Ereignis extrahierte xdmEntity):
| code language-json |
|---|
|
Ereigniszuordnung:
| code language-json |
|---|
|
formatierter Transformator:
| code language-jsonata |
|---|
|
Hinweis: Wenn ein Ereignis nach XDM-Schema-ID übereinstimmt, erhält der Transformator nur den
xdmEntityTeil des Ereignisses - nicht die äußere AJO-Hülle. Alle Pfade in Ihrem Transformatorausdruck sind relativ zum XDM-Entitätshauptteil.
Hinzufügen der JSON-Schemavalidierung
Das schema ist ein Pflichtfeld. Legen Sie sie auf ein JSON-Schema-Dokument fest, das als JSON-Zeichenfolge codiert ist, um die Struktur der eingehenden Ereignisse vor der Ausführung der Transformation zu überprüfen.
Ereignisse, bei denen die Schemavalidierung fehlschlägt, werden vor der Ausführung der Transformation zurückgewiesen. Die Fehlerantwort enthält den spezifischen Validierungsfehler, sodass falsch formatierte Upstream-Ereignisse einfach diagnostiziert werden können.
| code language-json |
|---|
|
Übergeben Sie dieses Schema als minimierte JSON-Zeichenfolge im Feld schema der Ereigniszuordnung.
Fallback - native Treueereignisse
Wenn eine Ereigniszuordnung nicht mit einem eingehenden Ereignis übereinstimmt, versucht die Plattform, es direkt als natives Adobe-Treueereignis aufzunehmen. Wenn die Payload bereits dem oben beschriebenen Treueprogramm-Ereignisformat entspricht, ist kein Transformator erforderlich und das Ereignis wird unverändert angewendet. Dadurch können Kunden, die ihre Ereignisse vorformatiert haben, die Transformation vollständig umgehen.
API-Referenz
Alle Vorgänge der Ereigniszuordnung verwenden den Basispfad /loyalty/metadata/config/events.
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
Validierung von Transformatoren
JSON-Datenausdrücke werden auf Syntax überprüft, wenn die Ereigniszuordnung gespeichert wird. Wenn der Ausdruck ungültig ist, gibt die API einen 422 mit einer Beschreibung des Analysefehlers zurück.
Um einen Transformator vor der Bereitstellung zu testen, verwenden Sie den JSONata Exerciser - fügen Sie Ihr Quellereignis als Eingabe und Ihren Transformatorausdruck ein, um zu überprüfen, ob die Ausgabe dem erwarteten Format des Treueereignisses entspricht.
Häufige Fehler
Diese Fehler laufen alle ohne Fehler auf einer einfachen Test-Payload mit einem einzelnen Element ab, was genau der Grund ist, warum sie unentdeckt durchrutschen. Testen Sie Ihren Transformator vor der Bereitstellung immer mit zwei oder mehr Produkten gegen eine Payload.
Der häufigste Fehler. Durch die Verwendung eines einzelnen Objektliterals mit productListItems.SKU wird jede SKU und jede Menge in zusammengefasste Sequenzen gezogen, anstatt einen Zeileneintrag pro Produkt zu erzeugen.
✗Reduziert alle Elemente in einer:
| code language-jsonata |
|---|
|
Bei zwei Produkten enthält item_set beide SKUs und quantity wird zu einem Array wie [1, 4].
✓Ein Zeileneintrag pro Produkt:
| code language-jsonata |
|---|
|
Die .{ }-Map wird einmal pro Produkt ausgeführt, sodass jeder Eintrag zu einem eigenen Eintrag wird.
identityMap.Email ist ein Array. Wenn ein Profil in diesem Namespace mehrere Identitäten hat, wird id ohne [0] zu einer Liste von Werten anstelle einer einzigen Zeichenfolge.
✗ identityMap.Email.id
✓ identityMap.Email[0].id
_yourtenant.identification.core.email. In Beispieldaten wird ein Wert zurückgegeben und das Aussehen ist korrekt, in Produktionsereignissen ist er jedoch häufig leer, sodass loyalty_identity.id null herauskommt. Verwenden Sie immer identityMap als Quelle der Identität.item_set gelangtDas Hinzufügen eines Kategoriefelds zu item_set ist einfach, aber wenn productCategories selbst ein Array ist, wird das Ergebnis unvorhersehbar erweitert.
✗führt möglicherweise zu mehr Einträgen als erwartet:
| code language-jsonata |
|---|
|
Ein Produkt mit drei Kategorien erzeugt eine item_set mit vier Werten.
✓Indizieren Sie das verschachtelte Array, um genau einen Wert zu erhalten:
| code language-jsonata |
|---|
|
item_list ist leer oder fehltEin Ereignis mit einer leeren oder fehlenden item_list wird als ungültig abgelehnt. Bei Ereignissen, die keine Transaktionen sind (Einchecken, benutzerdefinierte Trigger), gibt es keine natürlichen Zeileneinträge. Erstellen Sie daher einen synthetischen:
| code language-jsonata |
|---|
|
timestamp als Unix-Epochenzahl anstelle von ISO 8601Die Plattform erwartet eine ISO 8601-Zeichenfolge. Wenn das Quellereignis Millisekunden seit der Epoche zurückliegt, konvertieren Sie es:
| code language-jsonata |
|---|
|
utc_offset ausgelassenutc_offset werden sowohl der Abgleich des DayPart-Fensters als auch das Zählen aufeinander folgender Tage übersprungen. Ordnen Sie den UTC-Versatz des Speichers oder Geräts von Ihrem Quellereignis zu, wo immer er verfügbar ist.xdmEntity, nicht aber die äußere AJO-Hülle. Alle Pfade müssen relativ zum XDM-Entitätsstamm sein. Wenn Ihr Ausdruck auf Felder verweist, die sich in der äußeren Hülle befinden (z. B. /body/xdmMeta/...), werden sie nicht gefunden und erzeugen im Hintergrund null.This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.
For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.
- TL;DR: This page explains how to configure Event Mapping schema validation and JSONata transformer expressions so that incoming customer events are matched and reshaped into the Adobe Loyalty Event format for Loyalty Challenges.
Intents:
- Understand how an Event Mapping identifies and claims incoming events through XDM schema ID matching.
- Write a JSONata transformer expression that reshapes a source event into the Adobe Loyalty Event format.
- Add JSON Schema validation to an event mapping to reject malformed events before transformation.
- Avoid common transformer mistakes such as collapsing multiple line items into one object or losing array indices on identity fields.
- Use the API operations to create, list, update, and delete event mappings.
- Understand the native Loyalty Event fallback for events that do not match any mapping.
Glossary:
- Event Mapping: a configuration that tells the platform which events to claim (matching) and how to reshape them (transformation) (product-specific)
- Adobe Loyalty Event: the JSON object format that the Challenge Service processes (product-specific)
- Transformer: a JSONata expression that receives the incoming event JSON and returns a valid Adobe Loyalty Event object (product-specific)
item_set: an array of string identifiers on a line item that challenge tasks’ include/exclude lists match against (product-specific)xdmSchemaId: the field on an event mapping that is compared against the schema ID read from an incoming event’s envelope to determine a match (product-specific)- Data Collection Core Service (DCCS): the service through which events carrying an XDM schema reference in their envelope arrive (product-specific)
- Native Loyalty Event: an event that is ingested directly, without a transformer, when it already conforms to the Adobe Loyalty Event format (product-specific)
Guardrails:
loyalty_identityis required and must containid, the member’s loyalty ID.item_listis required and must have at least one item; an empty item_list is rejected.item_setis required per item.timestampis required and must be ISO 8601.utc_offsetis recommended; it is needed for daypart matching and streak-day counting, and without it daypart window matching and consecutive-day streak counting are both skipped._idis optional, used for dedup if the org has duplicate detection enabled.sub_totalis optional; omitting it means zero spend for spend-threshold tasks.- In the Event Mapping configuration,
name,xdmSchemaId,schema, andtransformerare required fields;guidis system-assigned and read-only. - The platform walks the org’s event mappings in order and applies the first one that matches; events that do not match any mapping fall through to native ingestion.
event_nameis used only for internal metrics and reporting; it is not used as a task filter — task qualification is determined byitem_setcontents, not the event name.- Events that fail schema validation are rejected before transformation runs.
- If the transformer’s JSONata expression is invalid, the API returns a
422error with a description of the parse failure. - Once a match is found by
xdmSchemaId, thexdmEntitybody — not the outer envelope — is passed to the transformer; for DCCS events specifically, paths referencing the outer envelope (e.g./body/xdmMeta/...) will not be found and will silently produce null. identityMapis an array per namespace; omitting[0]causes JSONata to return a sequence instead of a single value when more than one identity is present, turningloyalty_identity.idinto a list.- Custom tenant identity-like fields (e.g.
_yourtenant.identification.core.email) are frequently empty in production events even though they return a value in sample data;identityMapis the reliable source of identity. - Using a single object literal with a path like
productListItems.SKUinstead of mapping over the array (productListItems.{ ... }) collapses multiple line items into one, withquantitybecoming an array instead of a per-item value. - If a nested array field (e.g.
productCategories) is added toitem_setwithout indexing it, the result can expand to more entries than expected. timestampmust be ISO 8601; a Unix epoch integer must be converted (e.g. with$fromMillis).- Dividing
unit_priceby quantity is only correct if the source field is a line total; dividing an already-per-unit price by quantity silently produces a wrong value.
Terminology:
- Canonical name: Event Mapping — no documented named variant; the page refers back to an event mapping informally as “this definition” in context, not as a defined synonym.
- Canonical name: Adobe Loyalty Event — variants: Loyalty Event format
- Acronym: XDM — Experience Data Model (expansion per the acronyms list; not spelled out on this page, which uses only “XDM”)
- Acronym: DCCS — expansion not given on the page (“Data Collection Core Service” is the page’s own spelled-out form on first use, not an approved-list acronym)
- Do not confuse: “the outer AJO envelope” (never passed to the transformer) ≠ “the
xdmEntitybody” (what the transformer always receives once a match is found, per How Matching Works and the DCCS pitfall) - Do not confuse: “Event Mapping” (the matching-and-transformation configuration) ≠ “transformer” (the JSONata expression field within an event mapping)
FAQ:
- Q: How does the platform decide which event mapping applies to an incoming event? — It reads the XDM schema ID from the event’s envelope, walks the org’s event mappings in order, and applies the first one whose
xdmSchemaIdmatches. - Q: What happens to an event that does not match any event mapping? — It falls through to native ingestion as a native Adobe Loyalty Event; if it already conforms to the Loyalty Event format, no transformer is needed.
- Q: What part of the event does the transformer receive once a match is found? — The
xdmEntitybody, not the outer envelope. - Q: What causes
loyalty_identity.idto become a list instead of a single string? — Omitting the[0]index on anidentityMapnamespace array when more than one identity is present. - Q: Why would
item_setcontain more entries than expected? — Because a nested array field (such asproductCategories) was added toitem_setwithout indexing it. - Q: What happens if
item_listis empty or missing? — The event is rejected as invalid. - Q: What happens if the transformer expression has invalid JSONata syntax? — The API returns a
422error with a description of the parse failure when the event mapping is saved.
Personas:
- admin: Can create, list, update, and delete event mappings through the API operations at the base path /loyalty/metadata/config/events. Each event mapping requires the name, xdmSchemaId, schema, and transformer fields; guid is system-assigned and read-only. The page states that the platform walks the org’s event mappings in order and applies the first one that matches, and that events failing schema validation are rejected before transformation runs. Where: “API Reference”.
Onboarding:
- Level: Intermediate
- First minimal step: Create an event mapping by sending a POST request to /loyalty/metadata/config/events with the name, xdmSchemaId, and transformer fields.
- Success check: Using the JSONata Exerciser, the transformer expression’s output for the source event matches the expected Adobe Loyalty Event format.