このページ:では、イベントマッピングによって受信イベントを識別し、フィールド要件、一致する動作、例、API操作など、JSONata式を使用してAdobe ロイヤルティイベント形式に変換する方法について説明します。
お客様の取引をロイヤルティチャレンジに適用する前に、チャレンジサービスが理解できる Adobe ロイヤルティイベント 形式である必要があります。 POS システム、モバイルアプリ、e コマースプラットフォームなどの顧客イベントでは、通常、顧客自身のデータスキーマを使用します。 イベント トランスフォーマは、アップストリーム システムに変更を加えることなく、このギャップを埋めます。
概要
イベントマッピングは、プラットフォームに2つのことを伝えます。
- 要求するイベント – 受信イベントがこの定義に属していることを認識する方法(一致)
- リシェイプする方法 – 顧客のフィールドをロイヤルティイベント形式(変換)にマッピングするJSONata式
組織ごとに複数のイベントマッピングを設定できます。 プラットフォームはそれらを順番に評価し、一致する最初のものを適用します。 どのマッピングにも一致しないイベントは、ネイティブ取り込みにフォールバックします( フォールバック – ネイティブロイヤルティイベント を参照)。
Adobeロイヤルティイベントのフォーマット
すべてのイベントマッピングでは、次の形式のJSON オブジェクトを生成する必要があります。 これは、チャレンジサービスが処理する入力です。
{
"_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)
}
]
}
フィールドノート
loyalty_identityid — メンバーのロイヤルティ IDを含める必要があります。item_listitem_settimestamputc_offset_idsub_totalイベントマッピングフィールド
guidname"Starbucks POS Purchase")xdmSchemaIdtransformerマッチングの仕組み
データ収集コアサービス(DCCS)を介して到着したイベントでは、エンベロープにXDM スキーマ参照が含まれます。 プラットフォームは/body/xdmMeta/schemaRef/idからスキーマ IDを読み取り、各定義のxdmSchemaIdと比較します。
プラットフォームは、組織のイベントマッピング を順番に歩き、最初の一致を適用します。 一致が見つかると、xdmEntity本文がトランスフォーマに渡されます。
トランスフォーマの書き方
transformer フィールドはJSONata式です。 受信イベント JSONを入力として受け取り、有効なAdobe Loyalty Event オブジェクトを返す必要があります。
ターゲット形式の各トップレベルフィールドを、ソースイベントの対応するパスにマッピングします。
| code language-jsonata |
|---|
|
この定義に一致するすべてのイベントが同じ論理アクティビティを表す場合、event_nameをハードコードします。
| code language-jsonata |
|---|
|
event_nameは内部指標とレポートに使用されます。 タスクフィルターとして使用されません。タスクの選定は、イベント名ではなくitem_set個のコンテンツによって決定されます。
DCCS ルートを介して到着するイベントの場合、メンバーのIDは通常、カスタムテナントプロパティではなく、標準のXDM identityMap フィールドに格納されます。 identityMapは名前空間でキー設定されたマップです。キー自体は名前空間名で、値はID オブジェクトの配列です。
| code language-jsonata |
|---|
|
-
名前空間置換:
Emailを、組織がロイヤルティメンバーに使用する名前空間に置き換えます –Loyalty、ECID、CRMIDなど。プライマリロイヤルティプロファイル IDを保持する名前空間から常に読み取ります。 -
常に
[0]を使用:identityMap.Emailは配列です。 インデックスを使用しない場合、複数のIDが存在し、loyalty_identity.idがリストになる場合、JSONataは1つの値ではなくシーケンスを返します。[0]を持つ最初の要素にピン留めします。 -
IDのカスタムテナントフィールドを使用しない: カスタムフィールドグループでは、電子メールのようなフィールドが公開されることがあります(例:
_yourtenant.identification.core.email)。 サンプルデータでは、これは値を返し、正しく見えますが、実稼動イベントでは頻繁に空になります。 信頼できるID ソースは常にidentityMapです。
item_setを作成していますitem_setは文字列識別子の配列です。 チャレンジタスクがフィルタリングされる可能性のあるすべてのフィールドを含めます。
| code language-jsonata |
|---|
|
非トランザクションイベント(チェックイン、アンケート完了、カスタムトリガー)の場合は、1つのIDで十分です。
| code language-jsonata |
|---|
|
unit_priceunit_priceは単価にする必要があります。 一部のソーススキーマでは、代わりにラインの合計(価格×数量)が保存されます。 ソースフィールドがラインの合計である場合は、数量で割って単価を取得します。
| code language-jsonata |
|---|
|
ソースフィールドが行合計の場合にのみ分割します。 既に単価を保管している場合は、それを直接マッピングします。単価を数量で割ると、誤った値が生成されます。
transaction_idソースイベントにトランザクション IDが含まれていない場合は、タイムスタンプから安定したIDを取得できます。
| code language-jsonata |
|---|
|
これにより、ISO タイムスタンプがエポックミリ秒に変換され、特定のイベントに対して決定論的な値が生成されます。 利用可能な場合は、プラットフォーム独自のID生成関数を使用します。
完全なJSONata関数ライブラリを使用できます。 便利な例:
| code language-jsonata |
|---|
|
例
シナリオ: モバイルアプリがチェックインイベントを送信します。 行項目はありません。イベント自体が対象アクティビティです。
受信イベント:
| code language-json |
|---|
|
イベントマッピング:
| code language-json |
|---|
|
書式設定されたトランスフォーマ (読みやすくするため):
| code language-jsonata |
|---|
|
Output Adobe ロイヤルティイベント:
| code language-json |
|---|
|
含める/除外の制限のないチャレンジタスクは、このイベントを対象となる訪問としてカウントします。単一のitem_set エントリ ["store-checkin"]は、すべての項目を許可する任意のタスクと一致します。
シナリオ:販売時点情報管理システムは、トランザクションペイロードを送信します。 各行項目にはSKUがあり、カテゴリに属しています。 チャレンジタスクでは、SKUとカテゴリーを使用して何が適しているかを判断します。
受信イベント:
| code language-json |
|---|
|
イベントマッピング:
| code language-json |
|---|
|
書式設定されたトランスフォーマ:
| code language-jsonata |
|---|
|
Output Adobe ロイヤルティイベント:
| code language-json |
|---|
|
include: ["BEVERAGE"]を持つチャレンジタスクは、コーヒー品目が選定され(そのitem_setには"BEVERAGE"が含まれます)、そのタスクに対する支出の$9.00が累積されます。 マフィン行項目は除外されます。
シナリオ:件のイベントはAdobe Journey Optimizerを流れます。 受信イベントは、既知のスキーマ IDを持つXDM エクスペリエンスイベントです。 プラットフォームは、パスと値のチェックではなく、スキーマ IDを使用して照合を行います。
受信XDM エンティティ本文 (AJO イベントから抽出されたxdmEntity):
| code language-json |
|---|
|
イベントマッピング:
| code language-json |
|---|
|
書式設定されたトランスフォーマ:
| code language-jsonata |
|---|
|
注: イベントがXDM スキーマ IDで一致する場合、トランスフォーマはイベントの
xdmEntity部分のみを受け取り、外側のAJO エンベロープは受け取りません。 トランスフォーマ式のすべてのパスは、XDM エンティティ本文に対する相対パスです。
JSON スキーマ検証の追加
schema フィールドは必須です。 変換を実行する前に、受信イベントの構造を検証するために、JSON文字列としてエンコードされたJSON スキーマ ドキュメントに設定します。
スキーマの検証に失敗したイベントは、変換の実行前に拒否されます。 エラー応答には特定の検証エラーが含まれるため、不正なアップストリームイベントを簡単に診断できます。
| code language-json |
|---|
|
このスキーマを最小化されたJSON文字列としてイベントマッピングのschema フィールドに渡します。
フォールバック – ネイティブロイヤルティイベント
イベントマッピングが受信イベントと一致しない場合、プラットフォームはネイティブのAdobe ロイヤルティイベントとして直接取り込もうとします。 ペイロードが既に上記のロイヤルティイベント形式に準拠している場合、トランスは必要なく、イベントはそのまま適用されます。 これにより、イベントが事前にフォーマットされている顧客は、変換を完全にバイパスできます。
API リファレンス
すべてのイベントマッピング操作では、基本パス /loyalty/metadata/config/eventsを使用します。
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
変圧器の検証
JSONata式は、イベントマッピングが保存されたときに構文について検証されます。 式が無効な場合、APIは解析エラーの説明を含む422 エラーを返します。
デプロイする前にトランスフォーマをテストするには、JSONata Exerciserを使用します。ソースイベントを入力として貼り付け、トランスフォーマ式を使用して、出力が期待されるロイヤルティイベント形式と一致することを確認します。
陥りやすい失敗
これらのミスはすべて、単純な1項目のテストペイロードでエラーなく実行されます。これはまさに、検出されずに失敗する理由です。 デプロイする前に、必ず2つ以上の製品でペイロードに対してトランスフォーマをテストしてください。
最も頻繁な間違い。 productListItems.SKUを持つ単一のオブジェクトリテラルを使用すると、すべてのSKUとすべての数量が、製品ごとに1行の項目を生成するのではなく、グループ化されたシーケンスに取り込まれます。
✗は、すべての項目を1つに折りたたみます:
| code language-jsonata |
|---|
|
2つの製品を使用すると、item_setは両方のSKUを保持し、quantityは[1, 4]のような配列になります。
✓製品ごとに1つの行項目:
| code language-jsonata |
|---|
|
.{ } マップは製品ごとに1回実行され、各製品が独自のエントリになります。
identityMap.Emailは配列です。 [0]を使用しない場合、プロファイルがその名前空間に複数のIDを持つ場合、idは単一の文字列ではなく値のリストになります。
✗ identityMap.Email.id
✓ identityMap.Email[0].id
_yourtenant.identification.core.emailなどの電子メール形式のフィールドが公開されることがあります。 サンプルデータでは値が返され、正しく見えますが、実稼動イベントでは頻繁に空になり、loyalty_identity.idがnullになります。 常にidentityMapをIDのソースとして使用してください。item_setに漏洩しているネストされた配列item_setにカテゴリーフィールドを追加するのは簡単ですが、productCategories自体が配列である場合、結果は予測不可能に展開されます。
✗は予想よりも多くのエントリを生成する可能性があります:
| code language-jsonata |
|---|
|
3つのカテゴリを持つ製品は、4つの値を持つitem_setを生成します。
✓ネストされた配列をインデックス化して、1つの値を正確に取得します:
| code language-jsonata |
|---|
|
item_listが空または見つかりませんitem_listが空または存在しないイベントは、無効として拒否されます。 非トランザクションイベント(チェックイン、カスタムトリガー)の場合、自然な行の項目はないので、合成の行を生成します。
| code language-jsonata |
|---|
|
timestampをISO 8601ではなくUnix エポック整数として使用プラットフォームにはISO 8601文字列が必要です。 ソースイベントがエポックからミリ秒単位で進行する場合は、次のように変換します。
| code language-jsonata |
|---|
|
utc_offsetが省略されましたutc_offsetを使用しない場合、日別ウィンドウのマッチングと連続日ストリーク数の両方がスキップされます。 ストアまたはデバイスのUTC オフセットを、ソースイベントが利用可能な場所からマッピングします。xdmEntity ボディのみを受け取り、外側のAJO エンベロープは受け取りません。 すべてのパスは、XDM エンティティのルートに対する相対パスである必要があります。 エクスプレッションが外側のエンベロープ(例:/body/xdmMeta/...)にあるフィールドを参照している場合、それらのフィールドは見つからず、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.