Eseguire iterazioni sui dati contestuali personalization-contexts

Scopri come utilizzare la sintassi di iterazione Handlebars per visualizzare elenchi dinamici di dati provenienti da varie origini nei messaggi, inclusi eventi, risposte di azioni personalizzate e altri dati contestuali.

Panoramica overview

Journey Optimizer fornisce l'accesso ai dati contestuali provenienti da più origini durante la personalizzazione dei messaggi. Puoi eseguire iterazioni su array da queste origini utilizzando la sintassi Handlebars nei canali nativi (email, push, SMS) per visualizzare contenuti dinamici come elenchi di prodotti, consigli o altri elementi ripetuti.

Origini di contesto disponibili:

Questa guida illustra come eseguire iterazioni su array da ciascuna di queste origini nei messaggi e come utilizzare gli array durante la configurazione delle attività di percorso. Inizia con Sintassi di iterazione Handlebars per comprendere le nozioni di base sulla personalizzazione dei messaggi, oppure passa a Utilizza gli array nelle espressioni di Percorso per scoprire come passare i dati degli array alle azioni personalizzate e alle ricerche di set di dati.

Sintassi di iterazione Handlebars syntax

Handlebars fornisce a {{#each}} helper l'iterazione su array. La sintassi di base è:

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

Punti chiave:

Iterazione dei dati evento event-data

I dati evento sono disponibili quando il percorso viene attivato da un evento. Ciò è utile per visualizzare i dati acquisiti al momento dell’avvio del percorso, ad esempio il contenuto del carrello, gli elementi dell’ordine o gli invii di moduli.

Percorso contesto per gli eventi

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

Esempio: Cart items from an event (Carrelli da un evento)

Se lo schema evento include un array productListItems (formato XDM standard), puoi visualizzare il contenuto del carrello come descritto nell'esempio seguente.

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

Esempio: array nidificati negli eventi

Per le strutture nidificate, utilizzare blocchi {{#each}} nidificati.

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

Ulteriori informazioni sulla nidificazione in Best practice.

Alterna le risposte di azione personalizzate custom-action-responses

Le risposte all'azione personalizzata contengono dati restituiti da chiamate API esterne. È utile per visualizzare informazioni in tempo reale dai sistemi, ad esempio punti fedeltà, consigli di prodotto, stato dell’inventario o offerte personalizzate.

Percorso contestuale per azioni personalizzate

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

Esempio: consigli di prodotto da un’API

Per scorrere un array di consigli di prodotti restituiti da un’azione personalizzata e visualizzarli come schede singole nel messaggio, vedi l’esempio seguente.

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

Esempio: array nidificati da azioni personalizzate

Per scorrere sopra una risposta di azione personalizzata contenente array nidificati (un array di oggetti, in cui ogni oggetto contiene un altro array), vedi l’esempio seguente. Ciò dimostra l'utilizzo di {{#each}} loop nidificati per accedere a più livelli di dati.

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

Per schemi di nidificazione più complessi, consulta Best practice.

Esempio: vantaggi del livello fedeltà

Per visualizzare i vantaggi dinamici in base allo stato di fedeltà, vedi l’esempio seguente.

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

Alterna i risultati della ricerca del set di dati dataset-lookup

L'attività di ricerca set di dati ti consente di recuperare dati dai set di dati Adobe Experience Platform durante il runtime di percorso. I dati arricchiti vengono memorizzati come array e possono essere iterati nei messaggi.

Ulteriori informazioni sulla configurazione dell'attività di ricerca del set di dati in questa sezione. La ricerca del set di dati è particolarmente efficace quando viene combinata con i dati dell'evento. Vedere Esempio: dati dell'evento arricchiti con la ricerca del set di dati per un caso d'uso pratico.

Percorso contesto per le ricerche dei set di dati

context.journey.datasetLookup.<activityID>.entities

Esempio: dettagli del prodotto da un set di dati

Se utilizzi un’attività di ricerca del set di dati per recuperare informazioni di prodotto in base agli SKU, vedi l’esempio di seguito.

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

Esempio: iterazione filtrata con dati del set di dati

Per filtrare i risultati della ricerca del set di dati durante l'iterazione e visualizzare solo gli elementi che corrispondono a criteri specifici (ad esempio, prodotti di una particolare categoria), utilizzare le istruzioni {{#if}} condizionali all'interno del ciclo {{#each}}. Vedi l’esempio seguente.

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

Ulteriori informazioni sul filtro condizionale in Best practice.

Esempio: calcolare i totali dalla ricerca del set di dati

Per calcolare e visualizzare i totali mentre si esegue l’iterazione sui risultati della ricerca di set di dati, vedi l’esempio seguente.

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

Usa proprietà tecniche del percorso technical-properties

Le proprietà tecniche del percorso consentono di accedere ai metadati sull'esecuzione del percorso, ad esempio l'ID percorso e gli identificatori supplementari. Questi possono essere utili se combinati con pattern di iterazione, in particolare per filtrare gli array in base a specifiche istanze di percorso.

Proprietà tecniche disponibili

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

Esempio: filtrare gli elementi array utilizzando l’identificatore supplementare

Quando si utilizzano identificatori supplementari in percorsi attivati da eventi con array, è possibile filtrare per visualizzare solo l'elemento rilevante per l'istanza di percorso corrente. Ulteriori informazioni sugli identificatori supplementari in questa guida.

Scenario: un percorso viene attivato con più prenotazioni, ma desideri visualizzare solo le informazioni per la prenotazione specifica (identificata dall'ID supplementare) che ha attivato questa istanza di percorso.

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

Esempio: Includi ID percorso per il tracciamento

Per includere l’ID percorso nel messaggio a scopo di tracciamento, vedi l’esempio seguente.

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

Combinare più origini di contesto combine-sources

Puoi combinare dati provenienti da origini diverse nello stesso messaggio per creare esperienze avanzate e personalizzate. In questa sezione vengono illustrati esempi pratici di utilizzo congiunto di più origini di contesto.

Origini di contesto che è possibile combinare:

Esempio: articoli del carrello con inventario in tempo reale

Per combinare i dati evento (contenuti del carrello) con i dati azione personalizzati (stato inventario), vedi il campione di seguito.

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

Esempio: dati evento arricchiti con la ricerca del set di dati

Per combinare SKU evento con informazioni dettagliate sul prodotto da una ricerca set di dati, vedi l'esempio seguente.

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

Esempio: combinare più origini con proprietà tecniche

Per combinare più origini di contesto (dati di profilo, dati di evento, azioni personalizzate e proprietà tecniche) in un singolo messaggio, vedi l’esempio seguente.

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

Altri tipi di contesto other-contexts

Mentre questa guida si concentra sull’iterazione rispetto agli array, per la personalizzazione sono disponibili altri tipi di contesto che in genere non richiedono l’iterazione. L’accesso a questi elementi è diretto anziché ripetuto ciclicamente:

Per informazioni sulla sintassi di personalizzazione completa e sugli esempi che utilizzano queste origini, consulta:

Utilizzare gli array nelle espressioni di Percorso arrays-in-journeys

Mentre le sezioni precedenti si concentrano sull’iterazione degli array nella personalizzazione dei messaggi utilizzando Handlebars, puoi anche lavorare con gli array durante la configurazione delle attività del percorso. Questa sezione spiega come utilizzare i dati array dagli eventi nelle espressioni di Percorso, in particolare quando si trasmettono dati ad azioni personalizzate o si utilizzano array con ricerche di set di dati.

Trasmettere i valori dell’array ai parametri delle azioni personalizzati arrays-to-custom-actions

Durante la configurazione di azioni personalizzate, spesso è necessario estrarre i valori dagli array di eventi e trasmetterli come parametri. Questa sezione descrive i pattern comuni.

Ulteriori informazioni sul passaggio delle raccolte in Trasmettere le raccolte nei parametri delle azioni personalizzate.

Estrarre un singolo valore da un array

Caso d'uso: ottieni un campo specifico da un array di eventi da passare come parametro di query in una richiesta 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}

Creare un elenco di valori da un array

Caso d'uso: crea un elenco separato da virgole di ID da passare come parametro di query (ad esempio, /products?ids=sku1,sku2,sku3).

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

Trasmettere un array di oggetti a un’azione personalizzata

Caso d'uso: invia una matrice completa di oggetti nel corpo di una richiesta (per POST o GET con corpo).

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

Utilizzare gli array con le ricerche dei set di dati arrays-with-dataset-lookup

Quando si utilizza l'attività di ricerca set di dati, è possibile passare una matrice di valori come chiavi di ricerca per recuperare dati arricchiti.

Esempio: cerca i dettagli del prodotto per tutti gli SKU in un array di eventi.

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

Limitazioni e pattern array-limitations

Tenere presenti queste limitazioni quando si lavora con array in percorsi:

Nessun loop dinamico su array nel flusso di percorso

I percorsi non possono creare loop dinamici in cui un nodo di azione viene eseguito più volte per ogni elemento di un array. Questo è intenzionale per evitare problemi di prestazioni inutili.

Operazione non consentita:

Modelli consigliati:

Ulteriori informazioni in Guardrail e limitazioni.

Considerazioni sulle dimensioni della matrice

Gli array di grandi dimensioni possono influire sulle prestazioni del percorso:

Esempio completo: array di eventi per azione personalizzata complete-example

Questo è un flusso di lavoro completo che mostra come utilizzare un array di eventi con un’azione personalizzata.

Scenario: quando un utente abbandona il carrello, invia i dati del carrello a un'API di consigli esterna per ottenere suggerimenti personalizzati, quindi visualizzali in un messaggio e-mail.

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

Best practice best-practices

Segui queste best practice durante l’iterazione di dati contestuali per creare una personalizzazione manutenibile ed performante.

Usa nomi di variabili descrittive

Scegli nomi di variabili che indichino chiaramente ciò su cui stai eseguendo l’iterazione. Questo rende il codice più leggibile e di facile gestione. Ulteriori informazioni sulla sintassi di personalizzazione:

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

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

Frammenti di espressione in cicli

Quando utilizzi frammenti di espressione all'interno di {{#each}} loop, tieni presente che non puoi trasmettere variabili con ambito di loop come parametri di frammento. Tuttavia, i frammenti possono accedere alle variabili globali definite nel contenuto del messaggio all’esterno del frammento.

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

Ulteriori informazioni sull'utilizzo di frammenti di espressione all'interno di cicli, inclusi esempi dettagliati e soluzioni alternative.

Gestire gli array vuoti

Utilizzare la clausola {{else}} per fornire contenuto di fallback quando un array è vuoto. Ulteriori informazioni sulle funzioni helper:

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

Combina con helper condizionali

Utilizza {{#if}} nei cicli per il contenuto condizionale. Ulteriori informazioni sulle regole condizionali e esempi nelle risposte alle azioni personalizzate e nelle sezioni di ricerca set di dati.

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

Limita iterazione per prestazioni

Per array di grandi dimensioni, è consigliabile limitare il numero di iterazioni:

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

Accedere ai metadati dell’array

Handlebars fornisce variabili speciali all'interno di loop utili per i pattern di iterazione avanzati:

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

Risoluzione dei problemi troubleshooting

Problemi di iterazione? In questa sezione vengono descritti problemi e soluzioni comuni.

Array non visualizzato

Problema: l'iterazione dell'array non mostra alcun contenuto.

Errori di sintassi

Problema: la convalida dell'espressione non riesce o il messaggio non viene visualizzato.

I frammenti di espressione non funzionano in loop

Problema: un frammento di espressione non visualizza il contenuto previsto quando viene utilizzato all'interno di un ciclo {{#each}} oppure mostra un output vuoto o imprevisto.

Verifica delle iterazioni

Utilizza modalità test percorso per verificare le iterazioni. Ciò è particolarmente importante quando si utilizzano azioni personalizzate o ricerche set di dati:

Argomenti correlati related-topics

Nozioni di base di Personalization: Introduzione alla personalizzazione | Aggiungi personalizzazione | Sintassi Personalization | Funzioni di supporto | Creare regole condizionali

Configurazione Percorso: Informazioni sugli eventi | Configurare azioni personalizzate | Trasmettere le raccolte nei parametri delle azioni personalizzate | Utilizzare le risposte alle chiamate API nelle azioni personalizzate | Risoluzione dei problemi relativi alle azioni personalizzate | Utilizzare i dati di Adobe Experience Platform nei percorsi | Utilizzare identificatori supplementari nei percorsi | Guardrail e limitazioni | Verifica il percorso

Funzioni espressione di Percorso: Editor espressioni avanzate | Funzioni di gestione della raccolta (prima, tutte, ultima) | Funzioni elenco (serializeList, filter, sort) | Funzioni array (head, tail)

Casi di utilizzo di Personalization: E-mail di abbandono carrello | Notifica stato ordine

Progettazione messaggi: Introduzione alla progettazione delle e-mail | Creare notifiche push | Creare messaggi SMS | Anteprima e verifica del contenuto