상황별 데이터 반복 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.