Itération sur des données contextuelles personalization-contexts

Découvrez comment utiliser la syntaxe d’itération Handlebars pour afficher dans vos messages des listes dynamiques de données provenant de diverses sources, y compris des événements, des réponses à des actions personnalisées 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, notification 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 directement à Utilisation de tableaux dans les 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 Handlebars pour l’itération syntax

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

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

Points clés :

Itération sur des 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 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 : articles dans le panier à partir 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 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 {{#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}}

Pour en savoir plus sur l’imbrication, voir les bonnes pratiques.

Itération sur les réponses à des actions personnalisées custom-action-responses

Les réponses à une action personnalisée 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 des stocks 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 à une 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 {{#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, voir les 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ération sur les résultats de la recherche de jeu de données dataset-lookup

L’activité Recherche de jeu de données permet de récupérer des données à partir 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.

Pour en savoir plus sur la configuration de l’activité Recherche de jeu de données, voir cette section. La recherche de jeu de données est particulièrement performante si elle est combinée avec des données d’événement. Voir Exemple : données d’événement enrichies par la recherche de jeu 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 : informations sur le produit dans un jeu de données

Si vous utilisez une activité 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 du jeu de données

Pour filtrer les résultats de la recherche de jeu 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 conditionnelles {{#if}} dans votre boucle {{#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}}

Pour en savoir plus sur le filtrage conditionnel, voir les bonnes pratiques.

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

Pour calculer et afficher des totaux lors de l’itération sur les résultats de la recherche de jeu 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>

Utiliser des propriétés techniques du 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’ID du parcours et des 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

Lorsque vous utilisez des 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. Pour en savoir plus sur les identifiants supplémentaires, voir ce guide.

Scénario : un parcours est déclenché avec plusieurs réservations, mais vous souhaitez afficher uniquement les informations sur la réservation (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>

Combiner 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 de plusieurs sources de contexte.

Combinaisons possibles de sources de contexte :

Exemple : articles dans le panier avec stocks en temps réel

Pour combiner les données d’événement (contenu du panier) avec les données d’une action personnalisée (statut des stocks), 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 contextes other-contexts

Bien que ce guide se concentre sur l’itération sur les tableaux, d’autres types de contexte sont disponibles à des fins de personnalisation qui ne nécessitent généralement pas d’itération. Ils sont accessibles directement, sans boucle :

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

Utiliser des 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 le cadre de la personnalisation des messages à l’aide de la syntaxe Handlebars, vous travaillez également avec des tableaux lors de la configuration des activités du parcours. Cette section explique comment utiliser les données de tableau issues 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.

Transmission de valeurs de tableau aux paramètres d’actions personnalisées arrays-to-custom-actions

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

Pour en savoir plus sur la transmission de collections, voir Transmission de collections dans des paramètres d’actions personnalisées.

Extraire une seule valeur d’un tableau

Cas d’utilisation : obtenir 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éer une liste de valeurs à partir d’un tableau

Cas d’utilisation : créer une liste d’ID 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 : envoyer un tableau complet d’objets dans un corps de requête (pour les requêtes POST ou GET avec corps).

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

Utiliser des 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 : rechercher les informations sur le produit pour tous les SKU d’un tableau d’événements.

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

Limites 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 du 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 incontrôlés.

Ce que vous ne pouvez pas faire :

Modèles recommandés à la place :

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

Considérations relatives à la taille des tableaux

Les tableaux volumineux peuvent avoir un impact sur les performances du parcours :

Exemple complet : tableau d’événements vers 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’une personne 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 facile à gérer.

Utiliser des noms de variables descriptifs

Choisissez des noms de variables qui indiquent clairement l’objet de l’itération. Cela rend votre code plus lisible et plus facile à gérer. Pour 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

Lorsque vous utilisez des fragments d’expression dans des boucles {{#each}}, sachez que vous ne pouvez pas transmettre de variables définies dans la 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 les boucles, y compris des exemples détaillés et des solutions supplémentaires.

Gérer des tableaux vides

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

{{#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 {{#if}} dans des boucles pour le contenu conditionnel. Pour en savoir plus sur les règles conditionnelles et obtenir des exemples, voir les sections Réponses aux actions 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}}

Limitation de 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éder aux métadonnées des tableaux

Handlebars fournit des variables spéciales dans les boucles qui facilitent l’utilisation de 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 liés à l’itération ? Cette section aborde les problèmes les plus courants et leurs solutions.

Le tableau ne s’affiche pas.

Problème : l’itération du 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 test de parcours pour vérifier vos itérations. Cela est particulièrement important lors de l’utilisation d’actions personnalisées ou de recherches de jeux de données :

Rubriques connexes related-topics

Principes de base de la personnalisation : Commencer avec la personnalisation | Ajouter une personnalisation | Syntaxe de personnalisation | Fonctions de l’assistant | 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ée | Utiliser des réponses d’appel API dans les actions personnalisées | Résoudre les problèmes liés aux actions personnalisées | Utiliser 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 votre parcours

Fonctions d’expression de parcours : Éditeur d’expression avancé | Fonctions de gestion des collections (first, all, last) | Fonctions de liste (serializeList, filter, sort) | Fonctions de tableau (head, tail)

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

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