Itérer sur les données contextuelles personalization-contexts

Découvrez comment utiliser la syntaxe d’itération Handlebars pour afficher des listes dynamiques de données provenant de diverses sources dans vos messages, y compris les événements, les réponses d’action personnalisée et d’autres données contextuelles.

Vue d’ensemble overview

Journey Optimizer permet d’accéder aux données contextuelles provenant de plusieurs sources lors de la personnalisation des messages. Vous pouvez effectuer une itération sur des tableaux à partir de ces sources à l’aide de la syntaxe Handlebars dans les canaux natifs (e-mail, push, SMS) pour afficher du contenu dynamique tel que des listes de produits, des recommandations ou d’autres éléments répétés.

Sources de contexte disponibles :

Ce guide vous explique comment effectuer une itération sur des tableaux à partir de chacune de ces sources dans vos messages et comment utiliser des tableaux lors de la configuration des activités de parcours. Commencez par Syntaxe d’itération Handlebars pour comprendre les principes de base de la personnalisation des messages, ou passez à Utiliser des tableaux dans des expressions de Parcours ​ pour savoir comment transmettre des données de tableau à des actions personnalisées et à des recherches de jeux de données.

Syntaxe de l’itération Handlebars syntax

Handlebars fournit la {{#each}} helper pour effectuer une itération sur des tableaux. La syntaxe de base est :

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

Points clés :

Itérer sur les données d’événement event-data

Les données d’événement sont disponibles lorsque votre parcours est déclenché par un ​ événement ​. Cela s’avère utile pour afficher les données capturées au moment du démarrage du parcours, telles que le contenu du panier, les éléments de commande ou les envois de formulaire.

Chemin d’accès au contexte pour les événements

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

Exemple : éléments du panier d’un événement

Si votre schéma d’événement comprend un tableau productListItems (format XDM standard), vous pouvez afficher le contenu du panier comme décrit dans l’exemple ci-dessous.

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

Exemple : tableaux imbriqués dans des événements

Pour les structures imbriquées, utilisez des blocs de {{#each}} imbriqués.

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

En savoir plus sur l’imbrication dans ​ Bonnes pratiques ​.

Effectuer une itération sur les réponses d’action personnalisées custom-action-responses

Action personnalisée les réponses contiennent des données renvoyées par des appels API externes. Cela s’avère utile pour afficher des informations en temps réel sur vos systèmes, telles que les points de fidélité, les recommandations de produits, le statut de l’inventaire ou les offres personnalisées.

Chemin d’accès au contexte pour les actions personnalisées

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

Exemple : recommandations de produit à partir d’une API

Pour effectuer une itération sur un tableau de recommandations de produits renvoyées par une action personnalisée et les afficher en tant que cartes individuelles dans votre message, consultez l’exemple ci-dessous.

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

Exemple : tableaux imbriqués à partir d’actions personnalisées

Pour effectuer une itération sur une réponse d’action personnalisée contenant des tableaux imbriqués (un tableau d’objets, où chaque objet contient un autre tableau), consultez l’exemple ci-dessous. Cela illustre l’utilisation de boucles de {{#each}} imbriquées pour accéder à plusieurs niveaux de données.

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

Pour des modèles d’imbrication plus complexes, consultez Bonnes pratiques.

Exemple : avantages du niveau de fidélité

Pour afficher les avantages dynamiques en fonction du statut de fidélité, reportez-vous à l’exemple ci-dessous.

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

Itérer sur les résultats de la recherche de jeu de données dataset-lookup

L’activité Recherche de jeu de données vous permet de récupérer des données de jeux de données Adobe Experience Platform pendant l’exécution du parcours. Les données enrichies sont stockées sous la forme d’un tableau et peuvent être itérées dans vos messages.

En savoir plus sur la configuration de l’activité de recherche de jeu de données dans cette section. La recherche de jeux de données est particulièrement puissante lorsqu’elle est combinée avec des données d’événement. Voir Exemple : données d’événement enrichies par la recherche de jeux de données pour un cas d’utilisation pratique.

Chemin d’accès au contexte pour les recherches de jeux de données

context.journey.datasetLookup.<activityID>.entities

Exemple : détails du produit d’un jeu de données

Si vous utilisez une activité de recherche de jeu de données pour récupérer des informations de produit en fonction des SKU, consultez l’exemple ci-dessous.

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

Exemple : itération filtrée avec des données de jeu de données

Pour filtrer les résultats de la recherche de jeux de données lors de l’itération et afficher uniquement les éléments correspondant à des critères spécifiques (par exemple, les produits d’une catégorie particulière), utilisez des instructions de {{#if}} conditionnel dans votre boucle de {{#each}}. Voir l’exemple ci-dessous.

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

En savoir plus sur le filtrage conditionnel dans ​ Bonnes pratiques ​.

Exemple : calcul de totaux à partir de la recherche de jeux de données

Pour calculer et afficher des totaux lors de l’itération sur les résultats de la recherche de jeux de données, consultez l’exemple ci-dessous.

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

Utilisation des propriétés techniques de parcours technical-properties

Les propriétés techniques du parcours permettent d’accéder aux métadonnées sur l’exécution du parcours, telles que l’identifiant du parcours et les identifiants supplémentaires. Elles peuvent s’avérer utiles lorsqu’elles sont combinées à des modèles d’itération, en particulier pour filtrer des tableaux en fonction d’instances de parcours spécifiques.

Propriétés techniques disponibles

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

Exemple : filtrage d’éléments de tableau à l’aide d’un identifiant supplémentaire

Lors de l’utilisation d’identifiants supplémentaires dans des parcours déclenchés par un événement avec des tableaux, vous pouvez filtrer afin d’afficher uniquement l’élément approprié pour l’instance de parcours active. En savoir plus sur les identifiants supplémentaires dans ce guide.

Scénario : un parcours est déclenché avec plusieurs réservations, mais vous souhaitez afficher les informations uniquement pour la réservation spécifique (identifiée par un ID supplémentaire) qui a déclenché cette instance de parcours.

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

Exemple : inclure l’ID de parcours pour le suivi

Pour inclure l’ID de parcours dans votre message à des fins de suivi, consultez l’exemple ci-dessous.

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

Combinaison de plusieurs sources de contexte combine-sources

Vous pouvez combiner des données provenant de différentes sources dans le même message pour créer des expériences riches et personnalisées. Cette section présente des exemples pratiques d’utilisation conjointe de plusieurs sources de contexte.

Les sources de contexte peuvent être combinées :

Exemple : articles de panier avec stock en temps réel

Pour combiner les données d’événement (contenu du panier) avec les données d’action personnalisée (statut d’inventaire), consultez l’exemple ci-dessous.

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

Exemple : données d’événement enrichies avec la recherche de jeu de données

Pour combiner les SKU d’événement avec des informations détaillées sur les produits issues d’une recherche de jeu de données, consultez l’exemple ci-dessous.

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

Exemple : combinaison de plusieurs sources avec des propriétés techniques

Pour combiner plusieurs sources de contexte (données de profil, données d’événement, actions personnalisées et propriétés techniques) en un seul message, consultez l’exemple ci-dessous.

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

Autres types de contexte other-contexts

Bien que ce guide se concentre sur l’itération sur les tableaux, d’autres types de contexte sont disponibles pour la personnalisation qui ne nécessitent généralement pas d’itération. Ils sont accessibles directement plutôt que par bouclage :

Pour obtenir une syntaxe de personnalisation complète et des exemples d’utilisation de ces sources, reportez-vous à :

Utilisation de tableaux dans les expressions de Parcours arrays-in-journeys

Bien que les sections précédentes se concentrent sur l’itération sur des tableaux dans la personnalisation des messages à l’aide de Handlebars, vous travaillez également avec des tableaux lors de la configuration des activités de parcours. Cette section explique comment utiliser les données de tableau des événements dans les expressions de Parcours, en particulier lors de la transmission de données à des actions personnalisées ou de l’utilisation de tableaux avec des recherches de jeux de données.

Transmettre des valeurs de tableau aux paramètres d’action personnalisés arrays-to-custom-actions

Lors de la configuration d’actions personnalisées, vous devez souvent extraire des valeurs des tableaux d’événements et les transmettre en tant que paramètres. Cette section couvre les modèles courants.

En savoir plus sur la transmission de collections dans Transmettre des collections dans des paramètres d’action personnalisés.

Extraire une seule valeur d’un tableau

Cas d’utilisation : obtenez un champ spécifique d’un tableau d’événements à transmettre en tant que paramètre de requête dans une requête 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}

Création d’une liste de valeurs à partir d’un tableau

Cas d’utilisation : créez une liste d’identifiants séparés par des virgules à transmettre en tant que paramètre de requête (par exemple, /products?ids=sku1,sku2,sku3).

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

Transmettre un tableau d’objets à une action personnalisée

Cas d’utilisation : envoyez un tableau complet d’objets dans un corps de requête (pour POST ou GET avec le corps).

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

Utilisation de tableaux avec les recherches de jeux de données arrays-with-dataset-lookup

Lors de l’utilisation de l’activité Recherche de jeu de données, vous pouvez transmettre un tableau de valeurs en tant que clés de recherche pour récupérer des données enrichies.

Exemple : recherchez les détails du produit pour tous les SKU d’un tableau d’événements.

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

Restrictions et modèles array-limitations

Gardez à l’esprit ces limites lorsque vous utilisez des tableaux dans des parcours :

Pas de boucle dynamique sur les tableaux dans le flux de parcours

Les parcours ne peuvent pas créer de boucles dynamiques dans lesquelles un nœud d’action est exécuté plusieurs fois pour chaque élément d’un tableau. Cela est intentionnel afin d’éviter des problèmes de performances d’emballement.

Ce que vous ne pouvez pas faire :

Modèles recommandés à la place :

En savoir plus sur la Mécanismes de sécurisation et limitations.

Considérations relatives à la taille des tableaux

Les baies volumineuses peuvent avoir un impact sur les performances du parcours :

Exemple complet : tableau d’événements pour une action personnalisée complete-example

Voici un workflow complet montrant comment utiliser un tableau d’événements avec une action personnalisée.

Scénario : lorsqu’un utilisateur abandonne son panier, envoyez les données du panier à une API de recommandation externe pour obtenir des suggestions personnalisées, puis affichez-les dans un 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}}

Bonnes pratiques best-practices

Suivez ces bonnes pratiques lors de l’itération sur les données contextuelles pour créer une personnalisation performante et maintenable.

Utiliser des noms de variables descriptifs

Choisissez des noms de variables qui indiquent clairement ce sur quoi vous effectuez une itération. Cela rend votre code plus lisible et plus facile à gérer. En savoir plus sur la syntaxe de personnalisation :

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

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

Fragments d’expression dans les boucles

Lors de l’utilisation de fragments d’expression dans des boucles d’{{#each}}, sachez que vous ne pouvez pas transmettre de variables de portée boucle en tant que paramètres de fragment. Cependant, les fragments peuvent accéder aux variables globales définies dans le contenu de votre message en dehors du fragment.

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

En savoir plus sur l’utilisation de fragments d’expression dans des boucles, y compris des exemples détaillés et des solutions supplémentaires.

Gérer les tableaux vides

Utilisez la clause {{else}} pour fournir un contenu de secours lorsqu’un tableau est vide. En savoir plus sur les fonctions helper :

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

Combinaison avec des assistants conditionnels

Utilisez des {{#if}} dans des boucles pour le contenu conditionnel. En savoir plus sur les règles conditionnelles et consultez des exemples dans les sections Réponses d’action personnalisées et Recherche de jeu de données.

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

Limiter l’itération pour les performances

Pour les tableaux volumineux, pensez à limiter le nombre d’itérations :

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

Accès aux métadonnées des tableaux

Handlebars fournit des variables spéciales dans les boucles qui aident à obtenir des modèles d’itération avancés :

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

Résolution des problèmes troubleshooting

Vous rencontrez des problèmes avec l’itération ? Cette section couvre les problèmes courants et les solutions.

Tableau non affiché

Problème : votre itération de tableau n’affiche aucun contenu.

Erreurs de syntaxe

Problème : la validation de l’expression échoue ou le message ne s’affiche pas.

Les fragments d’expression ne fonctionnent pas dans les boucles

Problème : un fragment d’expression n’affiche pas le contenu attendu lorsqu’il est utilisé dans une boucle {{#each}} ou affiche une sortie vide/inattendue.

Test de vos itérations

Utilisez le mode de test de parcours 🔗 pour vérifier vos itérations. Ceci est particulièrement important lors de l’utilisation de actions personnalisées ou recherches de jeux de données :

Rubriques connexes related-topics

Principes de base de Personalization : Prise en main de la personnalisation | Ajouter une personnalisation | Syntaxe de Personalization | Fonctions helper | Créer des règles conditionnelles

Configuration du Parcours : À propos des événements | Configurer des actions personnalisées | Transmettre des collections dans des paramètres d’action personnalisés | Utilisation des réponses d’appel API dans les actions personnalisées | Résolution des problèmes liés aux actions personnalisées | Utilisation des données Adobe Experience Platform dans les parcours ​ | Utiliser des identifiants supplémentaires dans les parcours ​ | Mécanismes de sécurisation et limitations | Tester le parcours ​

Fonctions d'expression de Parcours : Éditeur d'expression avancé | Fonctions de gestion des collections (en premier, en dernier) | Fonctions de liste (serializeList, filter, sort) | Fonctions de tableau (head, tail)

Cas d’utilisation de Personalization : E-mail d’abandon de panier | Notification du statut de la commande

Conception de message : Prise en main de la conception d’e-mails | Créer des notifications push | Créer des SMS | Prévisualiser et tester votre contenu