反覆處理內容資料 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. 在您的自訂動作中，使用型別string設定查詢引數（例如sku）
2. 將其標籤為Variable以允許動態值

動作引數中的歷程運算式：

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

說明：

• @event{YourEventName}：參考您的歷程事件
• .first(currentEventField.condition)：傳回符合條件的第一個陣列專案
• currentEventField：代表事件陣列中的每個專案，因為您會在其中重複執行
• .SKU：從相符的專案中擷取SKU欄位
• 結果： "SKU-1" （適用於動作引數的字串）

深入瞭解集合管理函式中的first函式。

自訂動作組態：

1. 使用型別string設定查詢引數（例如ids）
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.