Iteración sobre datos contextuales personalization-contexts

Aprenda a utilizar la sintaxis de la iteración Handlebars para mostrar listas dinámicas de datos de varias fuentes en los mensajes, incluidos eventos, respuestas de acciones personalizadas y otros datos contextuales.

Información general overview

Journey Optimizer proporciona acceso a datos contextuales de varios orígenes durante la personalización de mensajes. Puede iterar matrices de estos orígenes utilizando la sintaxis Handlebars en canales nativos (email, push, SMS) para mostrar contenido dinámico como listas de productos, recomendaciones u otros elementos repetitivos.

Orígenes de contexto disponibles:

Esta guía muestra cómo repetir matrices de cada una de estas fuentes en los mensajes, y cómo trabajar con matrices al configurar actividades de recorrido. Comience con Sintaxis de iteraciones de Handlebars para comprender los conceptos básicos de personalización de mensajes o salte a Trabaje con matrices en expresiones de Recorrido para aprender a pasar datos de matrices a acciones personalizadas y búsquedas de conjuntos de datos.

Sintaxis de iteración Handlebars syntax

Handlebars proporciona {{#each}} helper para iterar en matrices. La sintaxis básica es:

{{#each arrayPath as |item|}}
  <!-- Access item properties here -->
  {{item.property}}
{{/each}}

Puntos clave:

Iterar sobre datos de evento event-data

Los datos de evento están disponibles cuando el recorrido se activa mediante un evento. Esto resulta útil para mostrar los datos capturados en el momento en que comenzó el recorrido, como el contenido del carro de compras, los elementos de pedidos o los envíos de formularios.

Ruta de contexto para eventos

context.journey.events.<event_ID>.<fieldPath>

Ejemplo: Elementos de carro de compras de un evento

Si el esquema de evento incluye una matriz productListItems (formato XDM estándar 4}), puede mostrar el contenido del carro de compras como se detalla en el ejemplo siguiente.

{{#each context.journey.events.event_ID.productListItems as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

Ejemplo: matrices anidadas en eventos

Para las estructuras anidadas, utilice bloques anidados {{#each}}.

{{#each context.journey.events.event_ID.categories as |category|}}
  <h2>{{category.name}}</h2>
  <ul>
    {{#each category.items as |item|}}
      <li>{{item.title}}</li>
    {{/each}}
  </ul>
{{/each}}

Más información sobre cómo anidar en Prácticas recomendadas.

Iterar en respuestas de acciones personalizadas custom-action-responses

Las respuestas de acción personalizada contienen datos devueltos por llamadas a API externas. Esto resulta útil para mostrar información en tiempo real de sus sistemas, como puntos de lealtad, recomendaciones de productos, estados de inventario u ofertas personalizadas.

Ruta de contexto para acciones personalizadas

context.journey.actions.<actionName>.<fieldPath>

Ejemplo: Recomendaciones de producto desde una API

Para iterar una matriz de recomendaciones de productos devueltas por una acción personalizada y mostrarlas como tarjetas individuales en el mensaje, consulte el ejemplo siguiente.

{
  "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>

Ejemplo: matrices anidadas de acciones personalizadas

Para iterar una respuesta de acción personalizada que contenga matrices anidadas (una matriz de objetos, donde cada objeto contiene otra matriz), vea el ejemplo siguiente. Esto demuestra el uso de bucles {{#each}} anidados para acceder a varios niveles de datos.

{
  "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}}

Para ver patrones de anidación más complejos, consulte Prácticas recomendadas.

Ejemplo: Beneficios del nivel de fidelización

Para mostrar los beneficios dinámicos en función del estado de fidelidad, consulte el siguiente ejemplo.

{
  "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>

Iterar sobre resultados de búsqueda de conjuntos de datos dataset-lookup

La actividad de búsqueda de conjuntos de datos le permite recuperar datos de conjuntos de datos de Adobe Experience Platform durante el tiempo de ejecución del recorrido. Los datos enriquecidos se almacenan como una matriz y se pueden repetir en los mensajes.

Obtenga más información acerca de cómo configurar la actividad Búsqueda de conjuntos de datos en esta sección. La búsqueda de conjuntos de datos es particularmente eficaz cuando se combina con datos de evento. Vea Ejemplo: Datos de evento enriquecidos con la búsqueda de conjuntos de datos para obtener un caso de uso práctico.

Ruta de contexto para búsquedas de conjuntos de datos

context.journey.datasetLookup.<activityID>.entities

Ejemplo: Detalles de un producto de un conjunto de datos

Si utiliza una actividad de búsqueda de conjuntos de datos para recuperar información del producto basada en SKU, consulte el siguiente ejemplo.

<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>

Ejemplo: Iteración filtrada con datos del conjunto de datos

Para filtrar los resultados de búsqueda del conjunto de datos durante la iteración y mostrar solo los elementos que coinciden con criterios específicos (por ejemplo, productos de una categoría en particular), utilice instrucciones {{#if}} condicionales dentro del bucle {{#each}}. Consulte el ejemplo siguiente.

<h2>Household Products</h2>
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {{#if product.category = "household"}}
    <div class="product">
      <h3>{{product.name}}</h3>
      <p>Price: ${{product.price}}</p>
    </div>
  {{/if}}
{{/each}}

Obtenga más información acerca del filtrado condicional en Prácticas recomendadas.

Ejemplo: Calcular totales de búsqueda de conjuntos de datos

Para calcular y mostrar los totales mientras se iteran los resultados de búsqueda del conjunto de datos, vea el ejemplo siguiente.

{% let householdTotal = 0 %}
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {%#if product.category = "household"%}
    {% let householdTotal = householdTotal + product.price %}
  {%/if%}
{{/each}}

<p>Your household products total: ${{householdTotal}}</p>

Usar propiedades técnicas del recorrido technical-properties

Las propiedades técnicas de recorrido proporcionan acceso a los metadatos sobre la ejecución de la recorrido, como el ID de recorrido y los identificadores suplementarios. Pueden resultar útiles cuando se combinan con patrones de iteración, especialmente para filtrar matrices basadas en instancias de recorrido específicas.

Propiedades técnicas disponibles

context.journey.technicalProperties.journeyUID
context.journey.technicalProperties.supplementalId

Ejemplo: Filtrado de elementos de matriz mediante un identificador suplementario

Cuando se utilizan identificadores suplementarios en recorridos activados por eventos con matrices, se puede filtrar para mostrar solo el elemento relevante para la instancia de recorrido actual. Obtenga más información acerca de los identificadores suplementarios en esta guía.

Escenario: se activa un recorrido con varias reservas, pero desea mostrar información solo para la reserva específica (identificada por el ID suplementario) que activó esta instancia de recorrido.

{{#each context.journey.events.event_ID.bookingList as |booking|}}
  {%#if booking.bookingInfo.bookingNum = context.journey.technicalProperties.supplementalId%}
    <div class="booking-details">
      <h3>Your Booking: {{booking.bookingInfo.bookingNum}}</h3>
      <p>Destination: {{booking.bookingInfo.bookingCountry}}</p>
      <p>Date: {{booking.bookingInfo.bookingDate}}</p>
    </div>
  {%/if%}
{{/each}}

Ejemplo: Incluir ID de recorrido para el seguimiento

Para incluir el ID de recorrido en el mensaje con fines de seguimiento, consulte el ejemplo siguiente.

<footer>
  <p>Journey Reference: {{context.journey.technicalProperties.journeyUID}}</p>
</footer>

Combinación de varias fuentes de contexto combine-sources

Puede combinar datos de diferentes fuentes en el mismo mensaje para crear experiencias personalizadas y enriquecidas. En esta sección se muestran ejemplos prácticos de cómo usar varias fuentes de contexto juntas.

Orígenes de contexto que se pueden combinar:

Ejemplo: Artículos del carro de compras con inventario en tiempo real

Para combinar datos de evento (contenido del carro de compras) con datos de acción personalizados (estado de inventario), vea el siguiente ejemplo.

<h2>Your Cart</h2>
{{#each context.journey.events.cartEvent.productListItems as |product|}}
  <div class="cart-item">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

<h2>We Also Recommend</h2>
{{#each context.journey.actions.GetRecommendations.items as |recommendation|}}
  <div class="recommendation">
    <h4>{{recommendation.name}}</h4>
    <p>${{recommendation.price}}</p>
    {{#if recommendation.inStock}}
      <span class="badge">In Stock</span>
    {{else}}
      <span class="badge out-of-stock">Out of Stock</span>
    {{/if}}
  </div>
{{/each}}

Ejemplo: datos de evento enriquecidos con la búsqueda de conjuntos de datos

Para combinar SKU de evento con información detallada del producto a partir de una búsqueda de conjunto de datos, vea el ejemplo a continuación.

<h2>Your Order Details</h2>
{{#each context.journey.events.orderEvent.productListItems as |item|}}
  <div class="order-item">
    <p><strong>SKU:</strong> {{item.SKU}}</p>
    <p><strong>Quantity:</strong> {{item.quantity}}</p>

    <!-- Enrich with dataset lookup data -->
    {{#each context.journey.datasetLookup.1234567.entities as |enrichedProduct|}}
      {{#if enrichedProduct.SKU = item.SKU}}
        <p><strong>Product Name:</strong> {{enrichedProduct.name}}</p>
        <p><strong>Category:</strong> {{enrichedProduct.category}}</p>
        <img src="{{enrichedProduct.imageUrl}}" alt="{{enrichedProduct.name}}" />
      {{/if}}
    {{/each}}
  </div>
{{/each}}

Ejemplo: combinación de varias fuentes con propiedades técnicas

Para combinar varias fuentes de contexto (datos de perfil, datos de evento, acciones personalizadas y propiedades técnicas) en un solo mensaje, vea el siguiente ejemplo.

<div class="personalized-content">
  <!-- Profile data -->
  <h1>Hello {{profile.person.name.firstName}},</h1>

  <!-- Event data iteration -->
  <h2>Your Recent Purchases</h2>
  {{#each context.journey.events.purchaseEvent.items as |purchase|}}
    <div class="purchase">
      <p>{{purchase.productName}} - ${{purchase.price}}</p>
    </div>
  {{/each}}

  <!-- Custom action response iteration -->
  <h2>Recommended for You</h2>
  {{#each context.journey.actions.GetPersonalizedRecs.recommendations as |rec|}}
    <div class="recommendation">
      <h3>{{rec.title}}</h3>
      <p>{{rec.description}}</p>
    </div>
  {{/each}}

  <!-- Technical properties -->
  <footer>
    <p class="fine-print">Journey ID: {{context.journey.technicalProperties.journeyUID}}</p>
  </footer>
</div>

Otros tipos de contexto other-contexts

Aunque esta guía se centra en la iteración en matrices, otros tipos de contexto están disponibles para la personalización que generalmente no requieren iteración. Se accede a ellas directamente en lugar de hacerlo en bucle:

Para obtener sintaxis de personalización completa y ejemplos con estas fuentes, consulte:

Trabajo con matrices en expresiones de Recorrido arrays-in-journeys

Mientras que las secciones anteriores se centran en repetir matrices en la personalización de mensajes mediante Handlebars, también puede trabajar con matrices al configurar actividades de recorrido. En esta sección se explica cómo utilizar datos de matriz de eventos en expresiones de Recorrido, especialmente al pasar datos a acciones personalizadas o al utilizar matrices con búsquedas de conjuntos de datos.

Pasar valores de matriz a parámetros de acción personalizados arrays-to-custom-actions

Al configurar acciones personalizadas, a menudo necesita extraer valores de matrices de eventos y pasarlos como parámetros. Esta sección trata sobre patrones comunes.

Obtenga más información sobre cómo pasar colecciones en Pasar colecciones a parámetros de acción personalizados.

Extraer un solo valor de una matriz

Caso de uso: obtenga un campo específico de una matriz de eventos para pasarlo como parámetro de consulta en una solicitud GET.

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

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

Creación de una lista de valores a partir de una matriz

Caso de uso: cree una lista de identificadores separados por comas para pasarlos como parámetro de consulta (por ejemplo, /products?ids=sku1,sku2,sku3).

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

Pasar una matriz de objetos a una acción personalizada

Caso de uso: Envíe una matriz completa de objetos en un cuerpo de solicitud (para POST o GET con cuerpo).

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

Usar matrices con búsquedas de conjuntos de datos arrays-with-dataset-lookup

Al usar la actividad de búsqueda de conjuntos de datos, puede pasar una matriz de valores como claves de búsqueda para recuperar datos enriquecidos.

Ejemplo: Busca detalles del producto para todos los SKU de una matriz de eventos.

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

Limitaciones y patrones array-limitations

Tenga en cuenta estas limitaciones al trabajar con matrices en recorridos:

Sin bucles dinámicos en matrices en el flujo de recorrido

Los recorridos no pueden crear bucles dinámicos en los que se ejecuta un nodo de acción varias veces para cada elemento de una matriz. Esto es intencional para evitar problemas de rendimiento fuera de control.

Lo que no puedes hacer:

Patrones recomendados:

Obtenga más información en Protecciones y limitaciones.

Consideraciones de tamaño de matriz

Las cabinas grandes pueden afectar al rendimiento del recorrido:

Ejemplo completo: Matriz de eventos para la acción personalizada. complete-example

Este es un flujo de trabajo completo que muestra cómo utilizar una matriz de eventos con una acción personalizada.

Escenario: cuando un usuario abandona el carro, envía los datos del carro a una API de recomendaciones externa para obtener sugerencias personalizadas y luego mostrarlas en un correo electrónico.

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

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

<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}}

Prácticas recomendadas best-practices

Siga estas prácticas recomendadas al iterar sobre datos contextuales para crear una personalización mantenible y con rendimiento.

Uso de nombres de variables descriptivos

Elija nombres de variables que indiquen claramente sobre qué está iterando. Esto hace que su código sea más legible y fácil de mantener. Más información sobre sintaxis de personalización:

<!-- Good -->
{{#each products as |product|}}
{{#each users as |user|}}
{{#each recommendations as |recommendation|}}

<!-- Less clear -->
{{#each items as |item|}}
{{#each array as |element|}}

Fragmentos de expresión en bucles

Cuando use fragmentos de expresión en {{#each}} bucles, tenga en cuenta que no puede pasar variables con ámbito de bucle como parámetros de fragmento. Sin embargo, los fragmentos pueden acceder a las variables globales que se definen en el contenido del mensaje fuera del fragmento.

{% 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}}

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

Obtenga más información sobre el uso de fragmentos de expresión dentro de bucles, incluidos ejemplos detallados y soluciones alternativas.

Gestión de matrices vacías

Utilice la cláusula {{else}} para proporcionar contenido de reserva cuando una matriz esté vacía. Más información sobre funciones de ayuda:

{{#each context.journey.actions.GetRecommendations.items as |item|}}
  <div>{{item.name}}</div>
{{else}}
  <p>No recommendations available at this time.</p>
{{/each}}

Combinación con ayudantes condicionales

Use {{#if}} en bucles para contenido condicional. Obtenga más información acerca de reglas condicionales y vea ejemplos en las secciones Respuestas de acciones personalizadas y Búsqueda de conjuntos de datos.

{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{#if product.onSale}}
      <span class="badge">On Sale!</span>
    {{/if}}
    {{#if product.newArrival}}
      <span class="badge">New</span>
    {{/if}}
  </div>
{{/each}}

Limitar iteración para rendimiento

Para matrices grandes, considere limitar el número de iteraciones:

<!-- Display only first 5 items -->
{{#each context.journey.actions.GetProducts.items as |product|}}
  {{#if @index < 5}}
    <div>{{product.name}}</div>
  {{/if}}
{{/each}}

Acceso a metadatos de matriz

Handlebars proporciona variables especiales dentro de bucles que ayudan con los patrones de iteración avanzados:

{{#each products as |product|}}
  <div class="product {{#if @first}}featured{{/if}}">
    {{@index}}. {{product.name}}
  </div>
{{/each}}

Resolución de problemas troubleshooting

¿Tiene problemas con la iteración? Esta sección cubre problemas y soluciones comunes.

La matriz no se muestra

Problema: La iteración de la matriz no muestra ningún contenido.

Errores de sintaxis

Problema: Error en la validación de la expresión o no se representa el mensaje.

Los fragmentos de expresión no funcionan en bucles

Problema: un fragmento de expresión no muestra el contenido esperado cuando se usa dentro de un bucle {{#each}}, o muestra un resultado vacío o inesperado.

Prueba de las iteraciones

Use modo de prueba de recorrido para comprobar las iteraciones. Esto es especialmente importante cuando se usan acciones personalizadas o búsquedas de conjuntos de datos:

Temas relacionados related-topics

Aspectos básicos de Personalization: Introducción a la personalización | Agregar personalización | Sintaxis de Personalization | Funciones de ayuda | Crear reglas condicionales

Configuración del Recorrido: Acerca de los eventos | Configurar acciones personalizadas | Pasar colecciones a parámetros de acción personalizados | Usar respuestas de llamadas API en acciones personalizadas | Solucionar problemas de tus acciones personalizadas | Usar datos de Adobe Experience Platform en recorrido | Usar identificadores suplementarios en los recorridos | Protecciones y limitaciones | Pruebe su recorrido

Funciones de expresión de Recorrido: Editor de expresiones avanzadas | Funciones de administración de colecciones (primero, todo, último) | Funciones de lista (serializeList, filter, sort) | Funciones de matriz (cabeza, cola)

Casos de uso de Personalization: Correo electrónico de abandono del carro de compras | Notificación de estado del pedido

Diseño de mensaje: Introducción al diseño de correo electrónico | Crear notificaciones push | Crear mensajes SMS | Previsualizar y probar tu contenido