Iterar em dados contextuais personalization-contexts

Saiba como usar a sintaxe de iteração do Handlebars para exibir listas dinâmicas de dados de várias fontes em suas mensagens, incluindo eventos, respostas de ação personalizadas e outros dados contextuais.

Visão geral overview

O Journey Optimizer fornece acesso a dados contextuais de várias fontes durante a personalização da mensagem. Você pode iterar matrizes dessas fontes usando a sintaxe Handlebars em canais nativos (email, push, SMS) para exibir conteúdo dinâmico como listas de produtos, recomendações ou outros elementos repetitivos.

Fontes de contexto disponíveis:

Este guia mostra como iterar sobre matrizes de cada uma dessas fontes em suas mensagens e como trabalhar com matrizes ao configurar atividades de jornada. Comece com Sintaxe de iteração Handlebars para entender as noções básicas de personalização de mensagens ou vá para Trabalhe com matrizes em expressões de Jornada para saber como transmitir dados de matriz para ações personalizadas e pesquisas de conjuntos de dados.

Sintaxe de iteração de Handlebars syntax

Handlebars fornece o {{#each}} auxiliar para iterar sobre matrizes. A sintaxe básica é:

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

Pontos principais:

Iterar dados do evento event-data

Os dados do evento estão disponíveis quando a sua jornada é acionada por um evento. Isso é útil para exibir dados capturados no momento em que a jornada foi iniciada, como conteúdo do carrinho, itens de pedido ou envios de formulário.

Caminho de contexto para eventos

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

Exemplo: itens do carrinho de um evento

Se o esquema de evento incluir uma matriz productListItems (formato XDM padrão), você poderá exibir o conteúdo do carrinho conforme detalhado na amostra abaixo.

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

Exemplo: matrizes aninhadas em eventos

Para estruturas aninhadas, use {{#each}} blocos aninhados.

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

Saiba mais sobre o aninhamento em Práticas recomendadas.

Iterar sobre respostas de ação personalizadas custom-action-responses

As respostas de ação personalizada contêm dados retornados de chamadas de API externas. Isso é útil para exibir informações em tempo real de seus sistemas, como pontos de fidelidade, recomendações de produtos, status do inventário ou ofertas personalizadas.

Caminho de contexto para ações personalizadas

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

Exemplo: recomendações de produto de uma API

Para iterar sobre uma matriz de recomendações de produto retornadas de uma ação personalizada e exibi-las como cartões individuais em sua mensagem, consulte o exemplo abaixo.

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

Exemplo: matrizes aninhadas de ações personalizadas

Para iterar sobre uma resposta de ação personalizada contendo matrizes aninhadas (uma matriz de objetos, em que cada objeto contém outra matriz), consulte o exemplo abaixo. Isso demonstra o uso de loops {{#each}} aninhados para acessar vários níveis de dados.

{
  "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 obter padrões de aninhamento mais complexos, consulte Práticas recomendadas.

Exemplo: benefícios do nível de fidelidade

Para exibir benefícios dinâmicos com base no status de fidelidade, consulte o exemplo abaixo.

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

Repetir nos resultados da pesquisa do conjunto de dados dataset-lookup

A Atividade de Pesquisa de Conjunto de Dados permite recuperar dados de conjuntos de dados do Adobe Experience Platform durante o tempo de execução da jornada. Os dados enriquecidos são armazenados como uma matriz e podem ser repetidos em suas mensagens.

Saiba mais sobre como configurar a atividade Pesquisa de Conjunto de Dados em esta seção. A pesquisa de conjunto de dados é particularmente eficiente quando combinada com dados de evento. Consulte Exemplo: dados de evento enriquecidos com a pesquisa de conjunto de dados para obter um caso de uso prático.

Caminho de contexto para pesquisas de conjunto de dados

context.journey.datasetLookup.<activityID>.entities

Exemplo: detalhes do produto de um conjunto de dados

Se você estiver usando uma atividade de Pesquisa de conjunto de dados para recuperar informações do produto com base em SKUs, consulte o exemplo abaixo.

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

Exemplo: iteração filtrada com dados do conjunto de dados

Para filtrar os resultados da pesquisa do conjunto de dados durante a iteração e exibir apenas itens que correspondam a critérios específicos (por exemplo, produtos de uma categoria específica), use instruções condicionais {{#if}} no loop {{#each}}. Veja o exemplo abaixo.

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

Saiba mais sobre a filtragem condicional em Práticas recomendadas.

Exemplo: Calcular totais a partir da pesquisa do conjunto de dados

Para calcular e exibir totais ao iterar pelos resultados da pesquisa do conjunto de dados, consulte o exemplo abaixo.

{% 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 propriedades técnicas do jornada technical-properties

As propriedades técnicas do Jornada fornecem acesso aos metadados sobre a execução da jornada, como a ID da jornada e os identificadores complementares. Eles podem ser úteis quando combinados com padrões de iteração, especialmente para filtrar matrizes com base em instâncias de jornada específicas.

Propriedades técnicas disponíveis

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

Exemplo: filtrar itens de matriz usando o identificador complementar

Ao usar identificadores complementares em jornadas acionadas por eventos com matrizes, você pode filtrar para mostrar somente o item relevante para a instância de jornada atual. Saiba mais sobre identificadores complementares em este guia.

Cenário: uma jornada é acionada com várias reservas, mas você deseja exibir informações somente para a reserva específica (identificada pela ID complementar) que acionou essa instância de jornada.

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

Exemplo: incluir ID da jornada para rastreamento

Para incluir a ID da jornada na mensagem para fins de rastreamento, consulte o exemplo abaixo.

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

Combinar várias fontes de contexto combine-sources

Você pode combinar dados de diferentes fontes na mesma mensagem para criar experiências ricas e personalizadas. Esta seção mostra exemplos práticos de uso de várias fontes de contexto juntas.

Fontes de contexto que você pode combinar:

Exemplo: itens do carrinho com inventário em tempo real

Para combinar dados de evento (conteúdo do carrinho) com dados de ação personalizados (status do inventário), visualize a amostra abaixo.

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

Exemplo: dados de evento enriquecidos com pesquisa de conjunto de dados

Para combinar SKUs de evento com informações detalhadas do produto de uma pesquisa de conjunto de dados, veja a amostra abaixo.

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

Exemplo: combinar várias fontes com propriedades técnicas

Para combinar várias fontes de contexto (dados de perfil, dados de evento, ações personalizadas e propriedades técnicas) em uma única mensagem, veja a amostra abaixo.

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

Outros tipos de contexto other-contexts

Embora este guia se concentre na iteração sobre matrizes, outros tipos de contexto estão disponíveis para personalização que normalmente não exigem iteração. Elas são acessadas diretamente em vez de serem colocadas em loop:

Para obter a sintaxe de personalização completa e exemplos usando essas fontes, consulte:

Trabalhar com matrizes em expressões de Jornada arrays-in-journeys

Embora as seções anteriores se concentrem em iterar sobre matrizes na personalização de mensagens usando Handlebars, você também trabalha com matrizes ao configurar atividades de jornada. Esta seção explica como usar dados de matriz de eventos em expressões de Jornada, especialmente ao transmitir dados para ações personalizadas ou usar matrizes com pesquisas de conjunto de dados.

Envio de valores de matriz para parâmetros de ação personalizados arrays-to-custom-actions

Ao configurar ações personalizadas, geralmente é necessário extrair valores de matrizes de eventos e passá-los como parâmetros. Esta seção aborda padrões comuns.

Saiba mais sobre como transmitir coleções em Transmitir coleções para parâmetros de ação personalizados.

Extrair um valor único de uma matriz

Caso de uso: obtenha um campo específico de uma matriz de eventos para passar como parâmetro de consulta em uma solicitação 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}

Criar uma lista de valores de uma matriz

Caso de uso: crie uma lista separada por vírgulas de IDs a serem transmitidas como um parâmetro de consulta (por exemplo, /products?ids=sku1,sku2,sku3).

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

Passar uma matriz de objetos para uma ação personalizada

Caso de uso: enviar uma matriz completa de objetos em um corpo de solicitação (para POST ou GET com corpo).

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

Usar matrizes com pesquisas de conjunto de dados arrays-with-dataset-lookup

Ao usar a atividade de Pesquisa de Conjunto de Dados, você pode passar uma matriz de valores como chaves de pesquisa para recuperar dados enriquecidos.

Exemplo: pesquisar detalhes do produto para todas as SKUs em uma matriz de eventos.

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

Limitações e padrões array-limitations

Esteja ciente destas limitações ao trabalhar com arrays no jornada:

Nenhum loop dinâmico em arrays no fluxo de jornada

O Jornada não pode criar loops dinâmicos em que um nó de ação é executado várias vezes para cada item em uma matriz. Isso é intencional para evitar problemas de desempenho descontrolados.

O que você não pode fazer:

Padrões recomendados:

Saiba mais em Medidas de proteção e limitações.

Considerações sobre o tamanho da matriz

Arrays grandes podem afetar o desempenho da jornada:

Exemplo completo: matriz de eventos para ação personalizada complete-example

Este é um fluxo de trabalho completo que mostra como usar uma matriz de eventos com uma ação personalizada.

Cenário: quando um usuário abandona o carrinho, envie os dados do carrinho para uma API de recomendação externa para obter sugestões personalizadas e, em seguida, as exiba em um email.

{
  "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áticas recomendadas best-practices

Siga essas práticas recomendadas ao iterar em dados contextuais para criar personalização executável e que possa ser mantida.

Usar nomes de variáveis descritivas

Escolha nomes de variáveis que indiquem claramente sobre o que você está iterando. Isso torna o código mais legível e fácil de manter. Saiba mais sobre a sintaxe de personalização:

<!-- 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 expressão em loops

Ao usar fragmentos de expressão dentro de {{#each}} loops, esteja ciente de que você não pode passar variáveis com escopo de loop como parâmetros de fragmento. No entanto, os fragmentos podem acessar variáveis globais definidas no conteúdo da mensagem fora do 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}}

Saiba mais sobre o uso de fragmentos de expressão dentro de loops, incluindo exemplos detalhados e soluções alternativas adicionais.

Lidar com matrizes vazias

Use a cláusula {{else}} para fornecer conteúdo de fallback quando uma matriz estiver vazia. Saiba mais sobre funções auxiliares:

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

Combinar com auxiliares condicionais

Use {{#if}} em loops para conteúdo condicional. Saiba mais sobre regras condicionais e veja exemplos nas seções Respostas de ação personalizadas e Pesquisa de conjunto de dados.

{{#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 iteração para desempenho

Para matrizes grandes, considere limitar o número de iterações:

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

Acessar metadados da matriz

Handlebars fornecem variáveis especiais em loops que ajudam nos padrões avançados de iteração:

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

Solução de problemas troubleshooting

Problemas com a iteração? Esta seção aborda problemas e soluções comuns.

Matriz não exibida

Problema: sua iteração de matriz não está mostrando conteúdo.

Erros de sintaxe

Problema: falha na validação da expressão ou a mensagem não é renderizada.

Fragmentos de expressão que não funcionam em loops

Problema: um fragmento de expressão não exibe o conteúdo esperado quando usado dentro de um loop {{#each}}, ou mostra uma saída vazia/inesperada.

Teste das iterações

Use o modo de teste de jornada para verificar suas iterações. Isso é especialmente importante ao usar ações personalizadas ou pesquisas de conjunto de dados:

Tópicos relacionados related-topics

Fundamentos do Personalization: Introdução à personalização | Adicionar personalização | Sintaxe do Personalization | Funções auxiliares | Criar regras condicionais

Configuração de Jornada: Sobre eventos | Configurar ações personalizadas | Envio de coleções em parâmetros de ação personalizados | Usar respostas de chamada de API em ações personalizadas | Solucionar problemas de ações personalizadas | Usar dados do Adobe Experience Platform no jornada | Usar identificadores complementares no jornada | Medidas de proteção e limitações | Testar sua jornada

Funções de expressão de Jornada: Editor de expressão avançado | Funções de gerenciamento de coleções (primeiro, todos, último) | Listar funções (serializeList, filtro, classificação) | Funções de matriz (head, tail)

Casos de uso do Personalization: Email de abandono de carrinho | Notificação do status do pedido

Design da mensagem: Introdução ao design de email | Criar notificações por push | Criar mensagens SMS | Visualizar e testar seu conteúdo