コンテキストデータの反復処理 personalization-contexts

API 応答：

{
  "recommendations": [
    {
      "productId": "12345",
      "productName": "Summer Jacket",
      "price": 89.99,
      "imageUrl": "https://example.com/jacket.jpg"
    },
    {
      "productId": "67890",
      "productName": "Running Shoes",
      "price": 129.99,
      "imageUrl": "https://example.com/shoes.jpg"
    }
  ]
}

メッセージのパーソナライゼーション：

<h2>Recommended for You</h2>
<div class="recommendations">
  {{#each context.journey.actions.GetRecommendations.recommendations as |item|}}
    <div class="product-card">
      <img src="{{item.imageUrl}}" alt="{{item.productName}}" />
      <h3>{{item.productName}}</h3>
      <p class="price">${{item.price}}</p>
    </div>
  {{/each}}
</div>

API 応答：

{
  "id": "84632848268632",
  "responses": [
    { "productIDs": [1111, 2222, 3333] },
    { "productIDs": [4444, 5555, 6666] },
    { "productIDs": [7777, 8888, 9999] }
  ]
}

メッセージのパーソナライゼーション：

<h2>Product Groups</h2>
{{#each context.journey.actions.GetProducts.responses as |response|}}
  <div class="product-group">
    <ul>
      {{#each response.productIDs as |productID|}}
        <li>Product ID: {{productID}}</li>
      {{/each}}
    </ul>
  </div>
{{/each}}

API 応答：

{
  "loyaltyTier": "gold",
  "benefits": [
    { "name": "Free shipping", "icon": "truck" },
    { "name": "20% discount", "icon": "percent" },
    { "name": "Priority support", "icon": "headset" }
  ]
}

メッセージのパーソナライゼーション：

<h2>Your {{context.journey.actions.GetLoyaltyInfo.loyaltyTier}} Member Benefits</h2>
<ul class="benefits">
  {{#each context.journey.actions.GetLoyaltyInfo.benefits as |benefit|}}
    <li>
      <span class="icon-{{benefit.icon}}"></span>
      {{benefit.name}}
    </li>
  {{/each}}
</ul>

データセット参照の設定：

• 参照キー：list(@event{purchase_event.products.sku})
• 返されるフィールド：["SKU", "category", "price", "name"]

メッセージのパーソナライゼーション：

<h2>Product Details</h2>
<table>
  <thead>
    <tr>
      <th>Product Name</th>
      <th>Category</th>
      <th>Price</th>
    </tr>
  </thead>
  <tbody>
    {{#each context.journey.datasetLookup.3709000.entities as |product|}}
      <tr>
        <td>{{product.name}}</td>
        <td>{{product.category}}</td>
        <td>${{product.price}}</td>
      </tr>
    {{/each}}
  </tbody>
</table>

シナリオの例：製品リストから価格が 0 を超える最初の SKU を抽出します。

イベントスキーマの例：

{
  "commerce": {
    "productListItems": [
      { "SKU": "SKU-1", "priceTotal": 10.0 },
      { "SKU": "SKU-2", "priceTotal": 0.0 },
      { "SKU": "SKU-3", "priceTotal": 20.0 }
    ]
  }
}

カスタムアクション設定：

1. カスタムアクションで、クエリパラメーター（例：sku）を string タイプで設定します
2. 動的な値を許可するには、Variable としてマークします

アクションパラメーターのジャーニー式：

@event{YourEventName.commerce.productListItems.first(currentEventField.priceTotal > 0).SKU}

説明：

• @event{YourEventName}：ジャーニーイベントを参照します
• .first(currentEventField.condition)：条件に一致する最初の配列項目を返します
• currentEventField：イベント配列内の各項目をループ処理する際に表します
• .SKU：一致した項目から SKU フィールドを抽出します
• 結果："SKU-1"（アクションパラメーターに適した文字列）

first 関数について詳しくは、コレクション管理関数を参照してください。

カスタムアクション設定：

1. クエリパラメーター（例：ids）を string タイプで設定します
2. Variable としてマークします

ジャーニー式：

serializeList(
  @event{YourEventName.commerce.productListItems.all(currentEventField.priceTotal > 0).SKU},
  ",",
  true
)

説明：

• .all(currentEventField.condition)：条件に一致するすべての配列項目を返します（リストを返します）

• currentEventField：イベント配列内の各項目をループ処理する際に表します

• .SKU: SKU 値のみを含めるようにリストをプロジェクト化します

• serializeList(list, delimiter, addQuotes)：リストを文字列に結合します

  • ","：区切り文字としてコンマを使用します
  • true：各文字列要素を引用符で囲みます

• 結果："SKU-1,SKU-3"（クエリパラメーターに適しています）

詳細情報：

• all 関数
• serializeList 関数

カスタムアクションのコレクション処理について詳しくは、カスタムアクションパラメーターへのコレクションの受け渡しを参照してください。

リクエスト本文の例：

{
  "ctxt": {
    "products": [
      {
        "id": "productA",
        "name": "Product A",
        "price": 20.1,
        "color": "blue"
      }
    ]
  }
}

カスタムアクション設定：

1. リクエスト本文で、products を listObject タイプとして定義します
2. Variable としてマークします
3. オブジェクトフィールド id、name、price、color を定義します（それぞれがマッピング可能になります）

ジャーニーキャンバス設定：

1. 詳細設定モードで、コレクション式を設定します。

   code language-javascript
   @event{YourEventName.commerce.productListItems.all(currentEventField.priceTotal > 0)}

2. コレクションマッピング UI で、次の操作を実行します。

   • id → productListItems.SKU にマッピング
   • name → productListItems.name にマッピング
   • price → productListItems.priceTotal にマッピング
   • color → productListItems.color にマッピング

Journey Optimizer は、アクションペイロード構造に一致するオブジェクトの配列を構築します。

詳しくは、カスタムアクションパラメーターへのコレクションの受け渡しを参照してください。

データセット参照の設定：

参照キーフィールドでは、list() を使用して配列パスをリストに変換します。

list(@event{purchaseEvent.productListItems.SKU})

これにより、データセットで参照するすべての SKU 値のリストが作成されます。 結果は、context.journey.datasetLookup.<activityID>.entities の配列として使用でき、メッセージ内で反復処理できます（データセット参照結果の反復処理を参照）。

手順 1：カスタムアクションを設定

カスタムアクション「GetCartRecommendations」を作成します。

• メソッド：POST
• URL：https://api.example.com/recommendations
• リクエスト本文：

{
  "cartItems": [
    {
      "sku": "string",
      "price": 0,
      "quantity": 0
    }
  ]
}

• cartItems を listObject および Variable タイプとしてマークします
• sku（文字列）、price（数値）、quantity（整数） のフィールドを定義します

詳しくは、カスタムアクションの設定を参照してください。

手順 2：応答ペイロードを設定

カスタムアクションで、応答を設定します。

{
  "recommendations": [
    {
      "productId": "string",
      "productName": "string",
      "price": 0,
      "imageUrl": "string"
    }
  ]
}

詳しくは、API 呼び出し応答の使用を参照してください。

手順 3：ジャーニー内のアクションを関連付け

1. 買い物かごの放棄イベントの後に、カスタムアクションを追加します

2. cartItems コレクションの詳細設定モードの場合：

   code language-javascript
   @event{cartAbandonment.commerce.productListItems.all(currentEventField.quantity > 0)}

3. コレクションフィールドをマッピングします。

   • sku → productListItems.SKU
   • price → productListItems.priceTotal
   • quantity → productListItems.quantity

手順 4：メールで応答を使用

メールコンテンツで、レコメンデーションを反復処理します。

<h2>We noticed you left these items in your cart</h2>
{{#each context.journey.events.cartAbandonment.productListItems as |item|}}
  <div class="cart-item">
    <p>{{item.name}} - Quantity: {{item.quantity}}</p>
  </div>
{{/each}}

<h2>You might also like</h2>
{{#each context.journey.actions.GetCartRecommendations.recommendations as |rec|}}
  <div class="recommendation">
    <img src="{{rec.imageUrl}}" alt="{{rec.productName}}" />
    <h3>{{rec.productName}}</h3>
    <p>${{rec.price}}</p>
  </div>
{{/each}}

手順 5：設定をテスト

ライブジャーニーを実行する前に、アクション設定の「テストリクエストを送信」機能を使用してカスタムアクションをテストし、作成されたリクエストと値を確認します。

1. ジャーニーテストモードを使用します
2. productListItems 配列を含むサンプルイベントデータでトリガーします
3. カスタムアクションが正しい配列構造を受け取ることを確認します
4. アクションテストログを確認します
5. メールをプレビューして、両方の配列が正しく表示されていることを確認します

詳しくは、カスタムアクションのトラブルシューティングを参照してください。

サポートされているパターン - グローバル変数の使用：

{% let globalDiscount = 15 %}

{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{fragment id='ajo:fragment123/variant456' mode='inline'}}
  </div>
{{/each}}

globalDiscount はメッセージ内でグローバルに定義されているので、フラグメントはこれを参照できます。

サポートされていないパターン - ループ変数の受け渡し：

{{#each products as |product|}}
  <!-- This will NOT work as expected -->
  {{fragment id='ajo:fragment123/variant456' currentProduct=product}}
{{/each}}

回避策：フラグメントを使用する代わりに、パーソナライゼーションロジックをループ内に直接含めるか、ループの外でフラグメントを呼び出します。

考えられる原因と解決策：

1. パスが正しくない：コンテキストソースに基づいて、配列への正確なパスを確認します。

   • イベントの場合：context.journey.events.<event_ID>.<fieldPath>
   • カスタムアクションの場合：context.journey.actions.<actionName>.<fieldPath>
   • データセット参照の場合：context.journey.datasetLookup.<activityID>.entities

2. 配列が空である：{{else}} 句を追加して、配列にデータがないかどうかを確認します。 例について詳しくは、ベストプラクティスを参照してください。

3. データがまだ使用できない：ジャーニーフロー内のメッセージアクティビティの前に、カスタムアクション、イベント、データセット参照アクティビティが実行されていることを確認します。

一般的なミス：

• 終了タグが欠落している：すべての {{#each}} には {{/each}} が必要です。 適切な構造について詳しくは、Handlebars 反復構文を参照してください。
• 変数名が正しくない：ブロック全体で変数名を一貫して使用します。 命名規則について詳しくは、ベストプラクティスを参照してください。
• パス区切り文字が正しくない：スラッシュやその他の文字ではなく、ドット（.）を使用します

考えられる原因と解決策：

1. ループ変数をパラメーターとして渡そうとしている：式フラグメントは、ループ範囲の変数（現在の反復項目など）をパラメーターとして受け取ることができません。 これは既知の制限です。

   解決策：次のいずれかの回避策を使用します。

   • フラグメントがアクセスできるグローバル変数をメッセージ内に定義する
   • フラグメントを使用する代わりに、パーソナライゼーションロジックをループ内に直接含める
   • ループ固有のデータを必要としない場合は、ループの外でフラグメントを呼び出す

2. フラグメントが使用できないパラメーターを想定している：フラグメントが特定の入力パラメーターを受け取るようにデザインされた場合、これらのパラメーターをループ内から渡すことができないと、フラグメントは正しく動作しません。

   解決策：フラグメントがアクセスできるグローバル変数を使用するようにアプローチを再構築します。 例について詳しくは、ベストプラクティス - ループ内の式フラグメントを参照してください。

3. 変数範囲が正しくない：フラグメントが、ループ範囲内にのみ存在する変数を参照しようとしている可能性があります。

   解決策：フラグメントに必要な変数をメッセージレベル（ループの外）で定義し、グローバルにアクセスできるようにします。

説明、例、推奨されるパターンなどについて詳しくは、ループ内の式フラグメントの使用を参照してください。

1. ジャーニーをテストモードで開始します
2. サンプルデータを使用してイベントまたはカスタムアクションをトリガーします
3. メッセージプレビューを確認し、反復が正しく表示されることを確認します
4. テストモードのログでエラーがないか確認します（カスタムアクションテストモードログを参照）

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 use Handlebars {{#each}} syntax to loop over arrays from contextual sources — events, custom action responses, dataset lookups, and technical properties — in message personalization, and how to work with arrays in journey expression syntax when configuring journey activities.

Intents:

• Iterate over event array data (e.g., cart items, order items) in message personalization using {{#each}}
• Iterate over custom action response arrays (e.g., product recommendations) in messages
• Iterate over dataset lookup result arrays in messages
• Combine data from multiple contextual sources in a single personalized message
• Pass array values to custom action parameters using journey expression syntax
• Use arrays as lookup keys in Dataset Lookup activities
• Apply best practices for empty array fallbacks, variable naming, performance, and expression fragment scoping

Glossary:

• Handlebars: A templating language used in Journey Optimizer message personalization for iteration ({{#each}}) and conditional rendering ({{#if}}). (product-specific)
• {{#each}} helper: Handlebars syntax for iterating over an array; each iteration exposes the current item via a named variable (e.g., |product|). (product-specific)
• Contextual data: Data available at message send time from journey sources — events, custom action responses, dataset lookups, and journey technical properties — as opposed to static profile attributes. (product-specific)
• currentEventField: A reference used in journey expressions (not Handlebars) to refer to each item in an event array during filtering or mapping operations.
• currentActionField: Used in journey expressions to refer to each item in a custom action response collection.
• currentDataPackField: Used in journey expressions to refer to each item in a data source collection.
• serializeList: A journey expression function that converts a list of values into a delimited string (e.g., comma-separated), suitable for use as a query parameter.
• Supplemental identifier: A journey-level identifier that distinguishes concurrent journey instances triggered by the same profile; used to filter an array to the item relevant to the current instance.

Guardrails:

• Journeys cannot create dynamic loops where one action node executes multiple times per array item — this is by design to prevent performance issues. Pass the entire array or a serialized list to a single custom action instead.
• Keep event payloads under 50KB total.
• Custom action response payloads should be under 100KB.
• Limit the number of dataset lookup keys and returned entities for performance.
• Expression fragments cannot receive loop-scoped variables (e.g., the current {{#each}} iteration item) as parameters — this is a known limitation. Use global variables or inline logic instead.
• Numeric event IDs must be wrapped in backticks in expression paths (e.g., context.journey.events.`1697323153`.fieldName); without backticks, the PQL parser raises a syntax error.

Terminology:

• Canonical name: Handlebars iteration — variants: {{#each}} loop, each loop, array iteration
• Do not confuse: Handlebars {{#each}} syntax (used in message content for iteration and display) ≠ journey expression syntax (used in journey activity configuration — uses functions like first, all, serializeList)
• Do not confuse: currentEventField (journey expressions over event arrays) ≠ currentActionField (custom action response collections) ≠ currentDataPackField (data source collections)
• Do not confuse: @index / @first / @last (Handlebars special variables, only available within {{#each}} loops in message content) ≠ first / head functions (journey expression functions for extracting single items, used in journey activity configuration)

FAQ:

• Q: What is the difference between Handlebars syntax and journey expression syntax when working with arrays? — Handlebars {{#each}} is used in message content for iteration and display. Journey expression syntax — using functions like first, all, and serializeList — is used in journey activity configuration (e.g., custom action parameters, conditions). They are distinct syntaxes used in different contexts.
• Q: Can I loop a journey action node so it executes once per array item? — No. Journeys cannot create dynamic loops that execute an action node multiple times per item. Instead, pass the entire array or a serialized list to a single custom action that processes all items, or use external aggregation.
• Q: Can I pass the current loop item to an expression fragment inside a {{#each}} loop? — No. Expression fragments cannot receive loop-scoped variables as parameters. Use global variables defined outside the loop, or include the personalization logic directly within the loop instead of using a fragment.
• Q: How do I display fallback content when an array is empty? — Use the {{else}} clause within the {{#each}} block. Content inside {{else}} is rendered when the array has no items.
• Q: What do @index, @first, and @last mean inside a {{#each}} loop? — These are special Handlebars variables available only within {{#each}} loops in message content: @index is the 0-based current iteration index, @first is true for the first iteration, and @last is true for the last iteration.