Inhaltsverzeichnis
Erste Schritte mit Herausforderungen im Zusammenhang mit der Treue
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 Ereignisdefinition 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 Ereignisdefinitionen konfiguriert werden. Die Plattform bewertet sie der Reihe nach und wendet das erste an, das übereinstimmt. Ereignisse, die keiner Definition entsprechen, fallen in die native Aufnahme (siehe Fallback - native Treueereignisse).
Das Adobe-Treueprogramm-Ereignisformat
Jede Ereignisdefinition 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 Ereignisdefinition
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 Ereignisdefinitionen der Organisation (Reihenfolge) durch 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 |
|---|
|
Ereignisdefinition:
| 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 |
|---|
|
Ereignisdefinition:
| 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 |
|---|
|
Ereignisdefinition:
| 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 (optional)
Wenn Sie möchten, dass die Plattform die Struktur der eingehenden Ereignisse vor der Umwandlung überprüft, legen Sie das Feld schema auf ein JSON-Schema-Dokument fest, das als JSON-Zeichenfolge codiert ist.
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 Ereignisdefinition.
Fallback - native Treueereignisse
Wenn eine Ereignisdefinition einem eingehenden Ereignis entspricht, 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 zur Ereignisdefinition verwenden den Basispfad /loyalty/metadata/config/events.
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
Validierung von Transformatoren
JSONata-Ausdrücke werden beim Speichern der Ereignisdefinition auf Syntax überprüft. 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.