对上下文数据进行迭代 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.