Auf dieser Seite Sie, wie Sie Belohnungsanbieter und Belohnungsdefinitionen konfigurieren, JSONata-Ausdrücke für Belohnungen schreiben und den Kontext verstehen, der zum Generieren von Payloads für die Erfüllung verwendet wird.
Wenn eine Challenge-Aufgabe, ein Meilenstein oder eine Challenge abgeschlossen und ein Belohnungswert konfiguriert wurde gibt die Plattform eine Belohnung aus, indem sie den HTTP-Endpunkt Ihres Belohnungsanbieters mit einer JSON-Payload aufruft. Eine Belohnungsdefinition beschreibt, welche Belohnung ausgegeben werden soll, und bietet einen JSONata-Ausdruck - rewardJsonata - der die genaue Payload formt, die Ihr Anbieter erwartet.
In diesem Handbuch wird beschrieben, wie Sie einen Belohnungsanbieter konfigurieren, Belohnungsdefinitionen erstellen, den rewardJsonata Ausdruck schreiben und verstehen, welcher Kontext zur Auswertungszeit für ihn verfügbar ist.
➡️ Erfahren Sie, wie Sie einen Anbieter von Treueprämien einrichten
Modell mit zwei Ebenen
Die Belohnungen sind in zwei Stufen organisiert:
Reward Provider (endpoint, auth, headers)
└── Reward Definition (denomination, rewardJsonata)
└── Reward Definition
└── ...
Ein Belohnungsanbieter stellt ein einzelnes externes Belohnungssystem dar und enthält die URL des Versandendpunkts, die Authentifizierung und alle benutzerdefinierten HTTP-Kopfzeilen. Ein Anbieter kann mehrere Belohnungsdefinitionen besitzen, die jeweils einen anderen Belohnungstyp oder eine andere von diesem Anbieter angebotene Bezeichnung beschreiben (z. B. „50 Sterne“, „Doppelsterne“, „Gratis-Artikel„).
Eine Challenge verweist auf den Anbieter und die Definition per GUID. Wenn eine Belohnung ausgegeben wird, bewertet die Plattform den rewardJsonata Ausdruck der Definition und sendet das Ergebnis an den Endpunkt des Anbieters.
Belohnungsanbieter- und Definitionsfelder
| table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 5-row-4 6-row-4 7-row-4 8-row-4 html-authored | |||
|---|---|---|---|
| Feld | Typ | Erforderlich | Beschreibung |
guid |
String |
Nein (vom System zugewiesen) | Eindeutige Kennung. Schreibgeschützt. |
name |
String |
Ja | Anzeigename, innerhalb der Organisation eindeutig. |
desc |
String |
Nein | Lesbare Beschreibung des Anbieters. |
enabled |
Boolean |
Nein | Wenn false, wird der VersandBelohnungen für alle Definitionen unter diesem Anbieter ausgesetzt. |
url |
String |
Ja | HTTP-Endpunkt, der die Belohnungs-Payload erhält. Die Plattform sendet die ausgewertete rewardJsonata an diese URL. |
additionalHeaders |
Object |
Nein | Benutzerdefinierte HTTP-Kopfzeilen, die in jede Versandanfrage werden sollen (z. B. API-Schlüssel Inhaltsüberschreibungen). |
maxRatePerSecond |
Integer |
Nein | Optionales Ratenlimit pro Anbieter (1-5000). Null bedeutet unbegrenzt. |
enableMTLS |
Boolean |
Nein | Ob der Endpunkt gegenseitiges TLS erfordert. |
| table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 5-row-4 6-row-4 7-row-4 html-authored | |||
|---|---|---|---|
| Feld | Typ | Erforderlich | Beschreibung |
guid |
String |
Nein (vom System zugewiesen) | Eindeutige Kennung. Schreibgeschützt. |
name |
String |
Ja | Anzeigename, innerhalb des Anbieters eindeutig. |
denomination |
String |
Nein | Die Einheit der Belohnung, die in der Anzeige verwendet wird in Ausdrücken verfügbar ist als reward.denomination(z. B. "Stars", "Points", "Miles"). |
desc |
String |
Nein | Beschreibung der Belohnung, Ausdrücke als reward.desc verfügbar. |
enabled |
Boolean |
Nein | Wenn false, ist diese Definition inaktivgibt keine Belohnungen aus. |
isDefault |
Boolean |
Nein | Markiert dies als die Sandbox-weite Standard Belohnungsdefinition. Es kann immer nur eine Standarddefinition für alle Anbieter vorhanden sein. Wenn einen neuen Standard festlegen, wird der vorherige Standard gelöscht. Wird zum automatischen Ausfüllen von Belohnungsdetails für Herausforderungen zum Zeitpunkt der Veröffentlichung verwendet. |
rewardJsonata |
String |
Ja | JSONata-Ausdruck, der zum Zeitpunkt Belohnungsproblems ausgewertet wird Erhält den vollständigen und muss die JSON-Payload POST an den Anbieter zurückgeben. |
Der Belohnungskontext
Wenn rewardJsonata ausgewertet wird, erhält es ein einzelnes Stammobjekt, das alles über das Belohnungsereignis Bekannte enthält. Alle Pfade in Ihrem Ausdruck sind relativ zu diesem Stamm.
{
"rewardContext": {
"rewardValue": "50",
"source": "challenge"
},
"reward": {
"name": "500 Stars",
"desc": "Issue 500 Stars to the member",
"denomination": "Stars",
"enabled": true
},
"task": { ... },
"milestone": { ... },
"challenge": { ... },
"timestamp": "2026-02-10T00:29:22.538+00:00"
}
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 | |
|---|---|
| Feld | Beschreibung |
rewardContext.rewardValue |
Die Zeichenfolge des Belohnungswerts, die für die Herausforderung, Aufgabe oder den Meilenstein konfiguriert wurde, die/der diese Ausgabe ausgelöst hat. |
rewardContext.source |
Was die Belohnung ausgelöst hat: "task", "challenge" oder "milestone". |
reward |
Die Belohnungsdefinition selbst — name, desc, denomination. |
task |
Die abgeschlossene Aufgabe, einschließlich ihrer accumulators, schedule und reward. |
task.accumulators.spend |
Gesamtzahl der von der Aufgabe kumulierten qualifizierten Ausgaben. |
task.accumulators.qty |
Gesamtzahl der von der Aufgabe kumulierten qualifizierten Elemente. |
task.accumulators.item_list |
Alle qualifizierten Elemente, die auf die Aufgabe angewendet wurden. Jeder Eintrag hat item, transactionId, timestamp, utcOffset, locationId. |
task.accumulators.item_list[-1] |
Das zuletzt angewendete Element (JSONata-negativer Index). Nützlich für die Suche nach der letzten Transaktions-ID oder dem letzten Zeitstempel. |
task.schedule.currentStreak |
Aktuelle Anzahl aufeinander folgender Besuche (für Streak-Herausforderungen). |
task.schedule.currentVisits |
Besuchsanzahl insgesamt (für Besuchsherausforderungen). |
milestone |
Der Meilenstein, der diese Belohnung ausgelöst hat, oder null, wenn nicht eine Meilensteinbelohnung. Enthält count und reward.rewardValue. |
challenge.profileId |
Die Treue-ID des Mitglieds. |
challenge.kvpCustom |
Benutzerdefinierte Schlüssel-Wert-Paare, die für die Challenge konfiguriert sind. Ein gängiges Muster für die Übergabe von Kampagnen-IDs, Produktnamen oder anbieterspezifischen Metadaten. |
challenge.name |
Name der Herausforderung. |
challenge._id |
Challenge-ID. |
timestamp |
ISO 8601-Zeitstempel der Belohnungsausgabe. |
Schreiben des rewardJsonata-Ausdrucks
Der Ausdruck empfängt den Belohnungskontext als Eingabe und muss ein JSON-Objekt zurückgeben - die an den Endpunkt des Anbieters gepostete Payload. Die Form dieses Objekts hängt vollständig von der API des Anbieters ab. Sie ordnen Kontextfelder welcher Struktur auch immer der Anbieter erwartet.
Der einfachste Fall: Der Provider benötigt eine Punktzahl und eine Mitglieds-ID, die beide aus dem Kontext bekannt sind.
| code language-jsonata |
|---|
|
Ausgabe:
| code language-json |
|---|
|
rewardContext.rewardValueist immer eine Zeichenfolge. Verwenden Sie$number(), um sie zu konvertieren, wenn Ihr Anbieter einen numerischen Wert erwartet.
kvpCustom für anbieterspezifische MetadatenAnbieter benötigen häufig Felder wie Kampagnen-IDs oder Quellsystem-Codes, die für jede Challenge-Ausführung spezifisch sind. Speichern Sie diese beim Verfassen der Herausforderung in challenge.kvpCustom und referenzieren Sie sie dann im Ausdruck. So bleibt der Ausdruck kampagnenübergreifend wiederverwendbar.
| code language-jsonata |
|---|
|
Sie können auch reward.kvpCustom für Konstanten verwenden, die für einen bestimmten Belohnungstyp und nicht pro Herausforderung festgelegt sind.
Aufgabenakkumulatoren halten Aufzeichnungen über jedes qualifizierte Ereignis bereit. Verwenden Sie item_list[-1] , um auf das zuletzt angewendete Element zuzugreifen - seine transactionId und timestamp sind für Audit-Trails und Deduplizierung auf Anbieterseite nützlich.
| code language-jsonata |
|---|
|
Bei benachrichtigungsbasierten Anbietern (Slack, Mobile Message, E-Mail) können Sie eine Nachrichtenzeichenfolge direkt mit dem & Verkettungsoperator von JSONata erstellen:
| code language-jsonata |
|---|
|
Ausgabe:
| code language-json |
|---|
|
Beispiele
Szenario: grundlegende Treuepunkte-API erwartet eine Mitglieder-ID und einen Punktbetrag.
Belohnungsdefinition:
| code language-json |
|---|
|
Formatierter Ausdruck:
| code language-jsonata |
|---|
|
Payload an Provider gepostet:
| code language-json |
|---|
|
Szenario: Anbieter benötigt einen strukturierten Prämiensatz, der Auditfelder, Kampagnenverweise und Mitgliederbeschreibungen enthält. Kampagnenspezifische Werte werden in challenge.kvpCustom gespeichert, sodass dieselbe Belohnungsdefinition über Kampagnen hinweg funktioniert, ohne den Ausdruck zu bearbeiten.
Challenge-kvpCustom (festgelegt bei der Bearbeitung der Challenge):
| code language-json |
|---|
|
Belohnungsdefinition:
| code language-json |
|---|
|
Formatierter Ausdruck:
| code language-jsonata |
|---|
|
Payload an Provider gepostet:
| code language-json |
|---|
|
Szenario: Streak Challenge gibt alle N Besuche eine Meilensteinbelohnung aus. Der Ausdruck enthält die Meilensteinanzahl und den aktuellen Stream für den anbieterseitigen Kontext.
Formatierter Ausdruck:
| code language-jsonata |
|---|
|
Payload an Provider gepostet (beim zweiten Meilenstein des Besuchs):
| code language-json |
|---|
|
Wenn
rewardContext.source"milestone"wird, wird dasmilestonemitcountundreward.rewardValuebefüllt. Wenn die Quelle"task"oder"challenge"ist, wirdmilestonenull.
API-Referenz
| code language-http |
|---|
|
Für alle Anfragen sind x-gw-ims-org-id und x-sandbox-name Kopfzeilen erforderlich.
Anbieter erstellen:
| code language-http |
|---|
|
| code language-http |
|---|
|
Erstellen Sie eine Belohnungsdefinition:
| code language-http |
|---|
|
Validierung von Ausdrücken
rewardJsonata Ausdrücke werden zum Zeitpunkt der Veröffentlichung auf Syntax überprüft. Wenn der Ausdruck ungültig ist, gibt die API einen 422 mit einer Beschreibung des Analysefehlers zurück.
Um einen Ausdruck vor der Veröffentlichung zu entwickeln und zu testen, verwenden Sie den JSONata Exerciser. Fügen Sie das Belohnungskontext-JSON als Eingabedokument und Ihren Ausdruck ein, um zu überprüfen, ob die Ausgabe mit den Erwartungen Ihres Anbieters übereinstimmt. Ein repräsentativer Belohnungskontext für jeden Trigger (task, milestone, challenge) wird in den obigen Beispielen gezeigt.
Häufige Fehler
rewardContext.rewardValue als Zahl ohne Konversion verwendet$number(rewardContext.rewardValue) umschließenchallenge.kvpCustom.someKey gibt null zurückkvpCustom vorhanden isttask.accumulators.item_list[-1] ist nulltimestamp aus dem Kontext .milestone Zugriff, wenn die Quelle "task" oder "challenge" istmilestone ist null; Ausdruck löst NULL-Felder aus oder erzeugt sierewardContext.source vor dem Zugriff auf milestone prüfen oder milestone nur in Definitionen verwenden, die an Meilenstein-Prämien angehängt sind{ "items": [...] }Anleitungsvideos video
➡️ Erfahren Sie, wie Sie einen Anbieter von Treueprämien einrichten
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 reward providers and reward definitions for Loyalty Challenges, including the fields involved, the reward context passed to the rewardJsonata expression, and how to write that expression to build the payload posted to a reward provider’s endpoint.
Intents:
- Configure a reward provider (endpoint, authentication, headers) and one or more reward definitions under it.
- Understand the fields available on reward providers and reward definitions, including which are required.
- Write a rewardJsonata expression that maps reward context fields onto the payload a provider expects.
- Use kvpCustom on a challenge to pass campaign-specific or provider-specific metadata without editing the expression.
- Use task accumulator data, such as the most recent item in item_list, inside an expression.
- Distinguish task, milestone, and challenge reward sources and access the milestone object correctly.
- Validate a rewardJsonata expression before publishing and troubleshoot common mistakes.
Glossary:
- Reward Provider (product-specific): represents a single external rewards system; holds the delivery endpoint URL, authentication, and custom HTTP headers.
- Reward Definition (product-specific): describes a distinct reward type or denomination offered by a provider, including its rewardJsonata expression.
- rewardJsonata (product-specific): a JSONata expression configured on a reward definition that is evaluated at reward-issue time and must return the JSON payload to POST to the provider.
- Reward context (product-specific): the single root object passed to rewardJsonata at evaluation time, containing rewardContext, reward, task, milestone, challenge, and timestamp.
- kvpCustom (product-specific): custom key-value pairs configured on a challenge (challenge.kvpCustom) or available as constants on a reward (reward.kvpCustom), used to pass campaign IDs, product names, or provider-specific metadata.
- isDefault (product-specific): marks a reward definition as the sandbox-wide default, used to auto-populate reward details on personalized challenges at publish time.
- item_list (product-specific): the list of all qualifying items applied to a task’s accumulators; item_list[-1] accesses the most recently applied item via JSONata negative indexing.
Guardrails:
nameandurlare required fields on a reward provider;guidis system-assigned and read-only.nameandrewardJsonataare required fields on a reward definition;guidis system-assigned and read-only.- When a reward provider’s
enabledfield is false, reward delivery is suspended for all definitions under that provider. - When a reward definition’s
enabledfield is false, that definition is inactive and will not issue rewards. - Only one reward definition across all providers may be marked as default (
isDefault) at a time; setting a new default clears the previous one. maxRatePerSecondon a reward provider accepts a value from 1 to 5000 (per provider); null means unlimited.rewardContext.rewardValueis always a string; it must be converted with$number()if the provider expects a numeric value.milestoneis null when the reward source is"task"or"challenge"; it is populated (withcountandreward.rewardValue) only whenrewardContext.sourceis"milestone".- rewardJsonata expressions are validated for syntax at publish time; an invalid expression causes the API to return a 422 error with a description of the parse failure.
challenge.kvpCustom.someKeyreturns null if the key was not set on the challenge at authoring time.task.accumulators.item_list[-1]is null if no items were applied before the reward was issued (a non-purchase event).- If a rewardJsonata expression returns an array instead of an object, the provider receives an unexpected payload structure; it must be wrapped in an outer object.
Terminology:
- Canonical name: Reward Provider — holds the endpoint, authentication, and headers for an external rewards system.
- Canonical name: Reward Definition — describes a reward type or denomination and its rewardJsonata expression; belongs to one Reward Provider.
- Do not confuse: “Reward Provider” (the external system’s endpoint, auth, and headers) ≠ “Reward Definition” (a specific reward type/denomination with its own rewardJsonata, nested under a provider).
- Do not confuse: “challenge.kvpCustom” (per-challenge custom metadata) ≠ “reward.kvpCustom” (constants fixed for a given reward type).
- Do not confuse:
rewardContext.rewardValue(the reward value string that triggered issuance) ≠milestone.reward.rewardValue(the reward value specific to a milestone).
FAQ:
- Q: What triggers a reward to be issued? — When a challenge task, milestone, or challenge completes and has a reward value configured, the platform issues a reward by calling the reward provider’s HTTP endpoint with a JSON payload.
- Q: What fields are required to create a reward provider? —
nameandurlare required;guidis system-assigned and read-only. - Q: What fields are required to create a reward definition? —
nameandrewardJsonataare required;guidis system-assigned and read-only. - Q: How many reward definitions can be marked as default? — Only one definition across all providers may be default at a time; setting a new default clears the previous one.
- Q: Why does rewardContext.rewardValue need conversion before use as a number? — Because rewardContext.rewardValue is always a string; use $number() to convert it if the provider expects a numeric value.
- Q: Why would challenge.kvpCustom.someKey return null? — Because the key was not set on the challenge at authoring time; ensure the key is present in kvpCustom on every challenge that uses the definition.
- Q: What happens if an invalid rewardJsonata expression is published? — The API returns a 422 error with a description of the parse failure.
- Q: Where can I test a rewardJsonata expression before publishing? — In the JSONata Exerciser, by pasting the reward context JSON as the input document and the expression to verify the output.
Troubleshooting:
task.accumulators.item_list[-1] is null— Cause: no items were applied before the reward was issued (a non-purchase event). Fix: guard with a conditional or use timestamp from context instead.milestone accessed when source is "task" or "challenge"— Cause: milestone is null in that case. Fix: check rewardContext.source before accessing milestone, or only use milestone in definitions attached to milestone rewards.Expression returns an array instead of an object— Cause: the provider receives an unexpected payload structure. Fix: wrap array-returning expressions in an outer object, for example{ "items": [...] }.challenge.kvpCustom.someKey returns null— Cause: the key was not set on the challenge at authoring time. Fix: ensure the key is present in kvpCustom on every challenge that uses this definition.422 error— Cause: the rewardJsonata expression is invalid at publish time. Fix: the API returns a description of the parse failure; use the JSONata Exerciser to develop and test the expression before publishing.
Examples:
- Simple fixed payload: maps
challenge.profileId,$number(rewardContext.rewardValue), andreward.denominationinto a memberId/points/currency object, producing{"memberId": "ADB-0000030", "points": 50, "currency": "Stars"}. - Using kvpCustom: an expression references
challenge.kvpCustom.campaignIdalongsidechallenge.profileIdandrewardContext.rewardValueto keep the expression reusable across campaigns. - Using task accumulator data: an expression uses
task.accumulators.item_list[-1].transactionIdand.timestampfor audit trails and deduplication on the provider side. - Constructing a text message: an expression concatenates strings with
&, for example"You just earned " & rewardContext.rewardValue & " " & reward.denomination & "!", producing{"text": "You just earned 50 Stars!"}. - Example 1 — Simple points provider: a Reward Definition with rewardJsonata mapping
challenge.profileId,$number(rewardContext.rewardValue), andreward.denominationtomemberId,pointQuantity, anddenomination, producing a payload withpointQuantity: 50. - Example 2 — Provider payload with campaign metadata: a Reward Definition builds an
awardPointsarray usingchallenge.kvpCustom.parentCampaignIdandchallenge.kvpCustom.productName(set on the challenge) plus task accumulator transaction data, so the same definition works across campaigns without editing the expression. - Example 3 — Milestone reward: an expression includes
milestone.countandtask.schedule.currentStreak; whenrewardContext.sourceis"milestone", the milestone object is populated withcountandreward.rewardValue.
Personas:
- admin: Can configure a reward provider with its endpoint URL, authentication, and additional headers, and create reward definitions under it. Can set maxRatePerSecond between 1 and 5000, or leave it null for unlimited. Can mark enabled to false on a provider or definition to suspend or stop reward delivery. The page states that only one reward definition across all providers may be isDefault at a time. Where: “Reward provider & definition fields”.
Onboarding:
- Level: Intermediate
- First minimal step: Paste the reward context JSON as the input document in the JSONata Exerciser and add your rewardJsonata expression.
- Success check: The output matches what your provider expects.