在此页面上:了解如何配置奖励提供者和奖励定义、编写奖励JSONata表达式以及了解用于生成履行有效负载的上下文。
当质询任务、里程碑或质询完成 并配置奖励值 时,平台将通过使用JSON有效负载调用奖励提供商的HTTP端点来发出奖励。 奖励定义描述了问题的奖励,并提供了一个JSONata表达式 — rewardJsonata — 该表达式可形成您的提供商期望的确切有效负载。
本指南介绍如何配置奖励提供者、创建奖励定义、编写rewardJsonata表达式以及了解在评估时可供其使用的上下文。
两级模型
奖励分为两个级别:
Reward Provider (endpoint, auth, headers)
└── Reward Definition (denomination, rewardJsonata)
└── Reward Definition
└── ...
奖励提供程序表示单个外部奖励系统 — 它包含投放端点URL、身份验证和任何自定义HTTP标头。 一个提供商可以保存多个奖励定义,每个定义描述该提供商提供的不同奖励类型或面额(例如“50颗星”、“双颗星”、“免费项目”)。
质询通过GUID引用提供程序和定义。 当发出奖励时,平台将评估定义的rewardJsonata表达式,并将结果POST到提供程序的端点。
奖励提供者和定义字段
| 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 | |||
|---|---|---|---|
| 字段 | 类型 | 必需 | 描述 |
guid |
String |
否(系统分配) | 唯一标识符。 只读。 |
name |
String |
是 | 显示名称,在组织内唯一。 |
desc |
String |
否 | 易于用户识别的提供商描述。 |
enabled |
Boolean |
否 | 当false时,已针对此提供程序下的所有定义暂停奖励投放。 |
url |
String |
是 | 接收奖励有效负载的HTTP端点。 平台POST将评估的 rewardJsonata输出输出输出输出到此URL。 |
additionalHeaders |
Object |
否 | 要包含在每 个投放请求中的自定义HTTP标头(例如API密钥、 内容类型覆盖)。 |
maxRatePerSecond |
Integer |
否 | 可选的每提供程序速率限制(1-5000)。 Null表示无限制。 |
enableMTLS |
Boolean |
否 | 端点是否需要双向TLS。 |
| 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 | |||
|---|---|---|---|
| 字段 | 类型 | 必需 | 描述 |
guid |
String |
否(系统分配) | 唯一标识符。 只读。 |
name |
String |
是 | 显示名称,在提供程序中唯一。 |
denomination |
String |
否 | 奖励的单位,用于显示 ,在表达式中为 reward.denomination(例如 "Stars"、"Points"、"Miles")。 |
desc |
String |
否 | 奖励的说明,在表达式中以reward.desc形式提供。 |
enabled |
Boolean |
否 | 当false时,此定义处于非活动状态并且不会发出奖励。 |
isDefault |
Boolean |
否 | 将此项标记为沙盒范围的默认 奖励定义。 一次只能对所有提供程序使用一个定义 作为默认值; 设置新的默认值会清除上一个定义。 用于在发布时自动填充 个性化挑战的奖励详细信息。 |
rewardJsonata |
String |
是 | JSONata表达式在 reward-issue时间进行计算。 接收完整的 奖励上下文,并且必须将JSON 有效负载返回给POST提供程序。 |
奖励上下文
评估rewardJsonata时,它会收到一个包含奖励事件已知所有内容的根对象。 表达式中的所有路径都与此根相关。
{
"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 | |
|---|---|
| 字段 | 描述 |
rewardContext.rewardValue |
在触发此发布的挑战、任务或里程碑上配置的奖励值字符串。 |
rewardContext.source |
触发奖励的内容: "task"、"challenge"或"milestone"。 |
reward |
RewardDefinition本身 — name、desc、denomination。 |
task |
正在完成任务,包括其accumulators、schedule和reward。 |
task.accumulators.spend |
任务累计的符合条件的总支出。 |
task.accumulators.qty |
任务累计的合格项目总数。 |
task.accumulators.item_list |
应用于任务的所有符合条件的项目。 每个条目都有item、transactionId、timestamp、utcOffset、locationId。 |
task.accumulators.item_list[-1] |
应用的最新项目(JSONata负索引)。 对于来源补充最后一个交易ID或时间戳非常有用。 |
task.schedule.currentStreak |
当前连续访问连续计数(针对连续挑战)。 |
task.schedule.currentVisits |
总访问计数(针对访问挑战)。 |
milestone |
触发此奖励的里程碑,或者null(如果不是里程碑奖励)。 包括count和reward.rewardValue。 |
challenge.profileId |
成员的忠诚度ID。 |
challenge.kvpCustom |
在挑战中配置的自定义键值对。 用于传递促销活动ID、产品名称或特定于提供商的元数据的常见模式。 |
challenge.name |
质询名称。 |
challenge._id |
挑战ID。 |
timestamp |
奖励发放的ISO 8601时间戳。 |
编写rewardJsonata表达式
表达式接收奖励上下文作为其输入,并且必须返回一个JSON对象,该对象有效负载已发布到提供程序的端点。 该对象的形状完全取决于提供程序的API;您可以将上下文字段映射到提供程序期望的任何结构。
最简单的情况是:提供程序需要点数和成员ID,两者均从上下文知道。
| code language-jsonata |
|---|
|
输出:
| code language-json |
|---|
|
rewardContext.rewardValue始终为字符串。 如果您的提供商需要数字值,请使用$number()进行转换。
kvpCustom用于特定于提供商的元数据提供商通常需要活动ID或源代码等字段,这些字段特定于每个质询运行。 创作挑战时将这些内容存储在challenge.kvpCustom中,然后在表达式中引用它们 — 保持表达式可跨营销活动重复使用。
| code language-jsonata |
|---|
|
您还可以将reward.kvpCustom用于固定为给定奖励类型而不是每个质询的常量。
任务累计器保存每个合格事件的记录。 使用item_list[-1]访问最近应用的项 — 它的transactionId和timestamp对于提供程序端的审核跟踪和重复数据删除非常有用。
| code language-jsonata |
|---|
|
对于基于通知的提供商(Slack、移动消息、电子邮件),您可以使用JSONata的&连接运算符直接构建消息字符串:
| code language-jsonata |
|---|
|
输出:
| code language-json |
|---|
|
示例
方案:基本会员积分API需要成员ID和点数。
奖励定义:
| code language-json |
|---|
|
格式化的表达式:
| code language-jsonata |
|---|
|
有效负载发布到提供程序:
| code language-json |
|---|
|
方案:提供商需要包含审核字段、营销活动引用和成员描述的结构化奖励记录。 促销活动特定的值存储在challenge.kvpCustom中,因此相同的奖励定义可以在促销活动之间使用,而无需编辑表达式。
挑战kvpCustom(创作挑战时设置):
| code language-json |
|---|
|
奖励定义:
| code language-json |
|---|
|
格式化的表达式:
| code language-jsonata |
|---|
|
有效负载发布到提供程序:
| code language-json |
|---|
|
情景: Streak质询每N次访问就发出一个里程碑式奖励。 表达式包括里程碑计数和提供程序端上下文的当前条纹。
格式化的表达式:
| code language-jsonata |
|---|
|
有效负载发布到提供程序(在第2次访问里程碑):
| code language-json |
|---|
|
当
rewardContext.source为"milestone"时,milestone对象已填充count和reward.rewardValue。 当源为"task"或"challenge"时,milestone为null。
API 参考
| code language-http |
|---|
|
所有请求都需要x-gw-ims-org-id和x-sandbox-name标头。
创建提供程序:
| code language-http |
|---|
|
| code language-http |
|---|
|
创建奖励定义:
| code language-http |
|---|
|
表达式验证
rewardJsonata表达式在发布时进行了语法验证。 如果表达式无效,则API返回包含分析失败说明的422错误。
若要在发布之前开发和测试表达式,请使用JSONata Exerciser。 将奖励上下文JSON粘贴为输入文档和您的表达式,以验证输出是否与提供商的期望相匹配。 上述示例中显示了每个触发器类型(task、milestone、challenge)的代表性奖励上下文。
常见错误
rewardContext.rewardValue用作无转换的数字$number(rewardContext.rewardValue)换行challenge.kvpCustom.someKey返回空值kvpCustom中存在密钥task.accumulators.item_list[-1]为空timestampmilestone在源为"task"或"challenge"时访问milestone为null;表达式抛出或生成null字段milestone之前检查rewardContext.source,或仅在附加到里程碑奖励的定义中使用milestone{ "items": [...] }操作说明视频 video
➡️观看如何设置忠诚度奖励提供商
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.