Contexte

Les étapes Contexte vous permettent de créer et de mettre à jour une ou plusieurs variables pour un utilisateur au fil de sa progression dans un Canvas. Par exemple, si vous avez un Canvas qui gère des remises saisonnières, vous pouvez utiliser une variable de contexte pour stocker un code de réduction différent à chaque fois qu’un utilisateur entre dans le Canvas.

Fonctionnement

Les étapes de contexte vous permettent de créer et d’utiliser des données temporaires pendant le parcours d’un utilisateur dans un Canvas spécifique. Ces données n’existent que dans ce parcours Canvas et ne persistent pas dans d’autres Canvas ou en dehors de la session.

Les variables de contexte n’existent que pour ce parcours Canvas spécifique. Elles ne modifient pas le profil de l’utilisateur de manière permanente et n’apparaissent pas dans d’autres Canvas. Elles sont donc idéales pour les informations temporaires qui ne sont pertinentes que pour une Campaign ou un workflow spécifique.

Conseil

Pour une référence complète sur les variables de contexte, y compris les types de données, l’utilisation et les bonnes pratiques, consultez la Référence des variables de contexte.

Dans une étape de contexte, vous pouvez définir ou mettre à jour jusqu’à 10 variables de contexte. Ces variables peuvent être utilisées pour personnaliser les délais, segmenter les utilisateurs de manière dynamique et enrichir les messages tout au long du Canvas. Par exemple, vous pourriez créer une variable de contexte pour l’heure de vol prévue d’un utilisateur, puis l’utiliser pour définir des délais personnalisés et envoyer des rappels.

Vous pouvez définir des variables de contexte de deux manières :

• À l’entrée du Canvas : Les propriétés de l’événement personnalisé ou du déclencheur API sont automatiquement renseignées en tant que variables de contexte.
• Dans une étape de contexte : Définissez ou mettez à jour manuellement les variables de contexte en ajoutant une étape de contexte.

Chaque variable de contexte nécessite un nom, un type de données et une valeur (définie à l’aide de Liquid ou de l’outil d’ajout de personnalisation). Une fois définies, vous pouvez référencer les variables de contexte dans l’ensemble du Canvas à l’aide de Liquid, par exemple {{context.${flight_time}}}. Dans le champ Nom de la variable de contexte, vous pouvez également saisir le nom de la variable de contexte ou le sélectionner dans le menu déroulant de l’éditeur d’étape. Pour plus de détails, consultez la Référence des variables de contexte.

Chaque entrée dans le Canvas redéfinit les variables de contexte en fonction des dernières données d’entrée et de la configuration du Canvas, ce qui permet aux utilisateurs d’avoir plusieurs parcours actifs avec leur propre contexte. Par exemple, si un client a deux vols à venir, il aura deux états de parcours distincts s’exécutant simultanément, chacun avec ses propres variables de contexte spécifiques au vol, comme l’heure de départ et la destination. Cela vous permet d’envoyer des rappels personnalisés concernant son vol de 14 h à destination de New York tout en envoyant des mises à jour différentes concernant son vol de 8 h à destination de Los Angeles le lendemain, afin que chaque message reste pertinent pour la réservation spécifique.

Traitement des utilisateurs et mise en lots

Les étapes de contexte traitent les utilisateurs par lots pour optimiser les performances. Lorsque les utilisateurs entrent dans une étape de contexte, Braze les traite par lots de 1 000 utilisateurs par défaut. Ces lots sont traités en parallèle, mais au sein de chaque lot, les utilisateurs sont traités de manière séquentielle.

Cela signifie :

Exemple : Si 3 500 utilisateurs entrent dans une étape de contexte avec du contenu connecté qui prend 650 ms par utilisateur :

• Braze crée 4 lots d’utilisateurs (1 000, 1 000, 1 000 et 500 utilisateurs dans cet exemple).
• Chaque lot traite les utilisateurs de manière séquentielle, donc un lot de 1 000 utilisateurs prend environ 10,8 minutes (650 secondes ; 1 000 × 650 ms).
• Les lots se terminent à des moments différents, de sorte que les utilisateurs arrivent progressivement à l’étape suivante au fur et à mesure que leur lot se termine.
• Les premiers utilisateurs peuvent atteindre l’étape suivante plusieurs minutes avant les derniers utilisateurs, en fonction de la taille du lot et des temps de réponse du contenu connecté.

Sans contenu connecté, les étapes de contexte sont traitées beaucoup plus rapidement car il n’y a pas d’appels API externes à attendre.

Considérations

• Vous pouvez définir jusqu’à 10 variables de contexte par étape de contexte.
• Chaque variable nécessite un nom unique (lettres, chiffres et underscores uniquement, jusqu’à 100 caractères).
• La taille totale de toutes les variables d’une étape ne peut pas dépasser 50 Ko.
• Les variables transmises via des déclencheurs API partagent le même espace de noms que celles créées dans les étapes de contexte ; redéfinir une variable dans une étape de contexte remplace la valeur de l’API.

Pour plus de détails et des cas d’utilisation avancés, consultez la référence des variables de contexte.

Créer une étape Contexte

Conseil

Il n’est pas nécessaire d’utiliser une étape Contexte pour référencer les propriétés de l’événement déclencheur dans les étapes Parcours d’audience ou Arbre décisionnel. Vous pouvez référencer les propriétés directement dans les groupes de filtres à l’aide du filtre Context Variable. Veillez à sélectionner le type de données approprié.

Étape 1 : Ajouter une étape

Ajoutez une étape à votre Canvas, puis glissez-déposez le composant depuis la barre latérale, ou sélectionnez le bouton plus et sélectionnez Contexte.

Étape 2 : Définir les variables

Remarque

Vous pouvez définir jusqu’à 10 variables de contexte pour chaque étape Contexte.

Pour définir une variable de contexte :

1. Donnez un nom à votre variable de contexte.
2. Sélectionnez un type de données.
3. Rédigez une expression Liquid manuellement ou utilisez Ajouter une personnalisation pour créer un extrait de code Liquid à partir d’attributs préexistants.
4. Sélectionnez Aperçu pour vérifier la valeur de votre variable de contexte.
5. (Facultatif) Pour ajouter des variables supplémentaires, sélectionnez Ajouter une variable de contexte et répétez les étapes 1 à 4.
6. Lorsque vous avez terminé, sélectionnez Terminé.

Vous pouvez désormais utiliser votre variable de contexte partout où vous utilisez Liquid, comme dans les étapes Message et Mise à jour de l’utilisateur, en sélectionnant Ajouter une personnalisation. Dans le champ Nom de la variable de contexte, vous pouvez également saisir le nom de la variable de contexte ou la sélectionner dans le menu déroulant de l’éditeur d’étape. Pour une présentation complète, consultez la Référence des variables de contexte.

Important

Lorsque vous faites référence à des variables de contexte, utilisez toujours le format {{context.${variable_name}}}.

Filtres des variables de contexte

Vous pouvez créer des filtres utilisant des variables de contexte dans les étapes Parcours d’audience et Arbre décisionnel.

Pour orienter les utilisateurs en fonction de la réponse d’une étape Agent, ajoutez l’étape Agent avant votre étape Parcours d’audience ou Arbre décisionnel. L’étape Agent stocke sa sortie dans le contexte du Canvas, que vous pouvez évaluer avec des filtres de variables de contexte dans ces étapes de branchement.

Si l’agent renvoie un objet et que vous souhaitez filtrer sur une propriété imbriquée, saisissez le chemin dans le champ Nom de la variable de contexte en utilisant la notation par points au lieu du seul nom de variable de niveau supérieur (par exemple, intent_agent.persona lorsque persona est imbriqué sous intent_agent).

Pour la configuration des filtres, la logique de comparaison et des exemples avancés, consultez la Référence des variables de contexte.

Important

Choix entre les types de filtre « Jour de l’année » et « Heure » : lorsque vous filtrez des variables de contexte contenant des dates, sélectionnez le type de comparaison approprié selon que la date se répète chaque année ou non. Utilisez « Jour de l’année » uniquement lorsque l’année n’est pas incluse dans la valeur produite par la variable de contexte.

• Utilisez « Jour de l’année » lorsque la date se répète chaque année (par exemple, les anniversaires, les dates commémoratives ou les fêtes comme Noël). Ce type de comparaison se base sur le jour de l’année (1-365/366), sans tenir compte de l’année.
• Utilisez « Heure » lorsque la date est absolue et ne se répète pas (par exemple, les dates de fin de contrat, les dates de rendez-vous ou les dates de renouvellement d’abonnement). Ce type de comparaison se base sur l’horodatage complet, année incluse.

L’utilisation de « Jour de l’année » pour des dates absolues peut produire des résultats incorrects ou inattendus, car le calcul ignore la composante année. Par exemple, si vous comparez une date de fin de contrat en avril pour déterminer si elle se situe dans les 63 prochains jours, « Jour de l’année » peut générer des correspondances erronées, car seuls les numéros de jour sont comparés (119 contre 359) sans tenir compte du fait qu’avril est en réalité dans 188 jours.

Prévisualiser les parcours utilisateur

Nous vous recommandons de tester et de prévisualiser vos parcours utilisateur pour vous assurer que vos messages sont envoyés à la bonne audience et que les variables de contexte produisent les résultats attendus.

Remarque

Si vous prévisualisez votre Canvas dans la section Preview & Test Send de l’éditeur, l’horodatage dans l’aperçu du message de test n’est pas standardisé en UTC, car ce panneau génère les aperçus sous forme de chaînes de caractères. Cela signifie que si un Canvas est configuré pour accepter un objet time, l’aperçu du message ne reflète pas fidèlement ce qui se produit lorsque le Canvas est en production. Pour tester votre Canvas de la manière la plus précise, nous vous recommandons de prévisualiser les parcours utilisateur à la place.

Veillez à observer les scénarios courants qui créent des variables de contexte invalides. Lorsque vous prévisualisez votre parcours utilisateur, vous pouvez consulter les résultats des étapes de délai personnalisées utilisant des variables de contexte, ainsi que toute comparaison d’audience ou d’arbre décisionnel qui associe les utilisateurs à des variables de contexte.

Si la variable de contexte est valide, vous pouvez la référencer tout au long de votre Canvas. Toutefois, si la variable de contexte n’a pas été créée correctement, les étapes suivantes de votre Canvas ne fonctionneront pas correctement non plus. Par exemple, si vous créez une étape de contexte pour attribuer aux utilisateurs un horaire de rendez-vous et que vous définissez la valeur de cet horaire à une date passée, l’e-mail de rappel dans votre étape de message ne sera pas envoyé.

Conversion des chaînes de contenu connecté en JSON

Lors d’un appel de contenu connecté dans une étape de contexte, le JSON renvoyé par l’appel est évalué comme un type de données chaîne de caractères, par souci de cohérence et de prévention des erreurs. Si vous souhaitez convertir cette chaîne en JSON, utilisez as_json_string. Par exemple :

1
2

{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

Résolution des problèmes

Variables de contexte non valides

Une variable de contexte est considérée comme non valide lorsque :

• Un appel à un contenu connecté intégré échoue.
• L’expression Liquid renvoie au moment de l’exécution une valeur qui ne correspond pas au type de données ou qui est vide (null).

Par exemple, si le type de données de la variable de contexte est Number mais que l’expression Liquid renvoie une chaîne de caractères, elle est non valide.

Dans ces cas :

• L’utilisateur passe à l’étape suivante.
• Les analyses de l’étape du Canvas comptabilisent cela comme Not Updated.

Lors de la résolution des problèmes, surveillez la métrique Not Updated pour vérifier que votre variable de contexte se met à jour correctement. Si la variable de contexte est non valide, vos utilisateurs peuvent continuer dans votre Canvas au-delà de l’étape de contexte, mais pourraient ne pas remplir les conditions pour les étapes ultérieures.

Consultez Types de données pour les exemples de configuration pour chaque type de données.

Délais d’envoi avec le contenu connecté

Tous les utilisateurs d’un lot sont traités avant que les utilisateurs ne passent à l’étape suivante. Une fois le traitement du lot terminé, les utilisateurs ayant réussi passent à l’étape suivante, tandis que les utilisateurs ayant échoué sont relancés séparément — les utilisateurs ayant réussi n’attendent pas que les tentatives de relance aboutissent avant de progresser.

Comportement des nouvelles tentatives

Les appels de contenu connecté dans un Canvas ne font l’objet de nouvelles tentatives que lorsque l’appel inclut :retry.

• Étapes de contexte et de mise à jour de l’utilisateur : Braze relance l’appel de contenu connecté au niveau de l’étape (jusqu’à cinq fois). Si chaque tentative échoue, l’utilisateur quitte le Canvas.
• Étapes de message : Le contenu connecté avec :retry utilise toujours le pipeline de messaging. Les destinataires sont mis en attente dans la file d’attente d’envoi pendant que Braze relance l’appel jusqu’à cinq fois. Si chaque tentative échoue, le message est abandonné et l’utilisateur passe à l’étape suivante.

Pour les étapes de contexte et de mise à jour de l’utilisateur, certaines erreurs d’étape pouvant faire l’objet de nouvelles tentatives — comme l’échec de la récupération d’un code promotionnel ou une erreur d’étape inattendue — peuvent déclencher des tentatives supplémentaires au niveau de l’étape avec des délais exponentiels (environ 13 fois) avant que Braze ne fasse quitter le Canvas à l’utilisateur.

Pour en savoir plus sur la balise :retry, consultez Nouvelles tentatives de contenu connecté.

Le temps nécessaire pour traiter tous les utilisateurs à travers une étape de contexte dépend de :

• Le nombre d’utilisateurs entrant dans l’étape
• L’utilisation ou non du contenu connecté (et son temps de réponse)
• La taille du lot (1 000 utilisateurs par lot par défaut)

Si votre endpoint de contenu connecté a des limites de débit, tenez compte du fait que les étapes de contexte traitent les utilisateurs de manière séquentielle au sein de chaque lot, ce qui permet de respecter naturellement les limites de débit. Cependant, plusieurs lots sont traités en parallèle, donc assurez-vous que votre endpoint peut gérer les requêtes simultanées provenant de plusieurs lots.

Standardisation de la cohérence des fuseaux horaires

Avec la disponibilité générale de Canvas Context, toutes les propriétés d’événement d’horodatage par défaut dans les Canvas basés sur une action sont en UTC. Ce changement s’inscrit dans un effort plus large visant à garantir une expérience plus prévisible et cohérente lors de la modification des étapes et des messages Canvas. Notez que ce changement impacte tous les Canvas basés sur une action, que le Canvas en question utilise une étape Context ou non.

Important

Dans tous les cas, nous recommandons fortement d’utiliser les filtres Liquid time_zone pour que les horodatages soient représentés dans le fuseau horaire souhaité. Vous pouvez consulter cette question fréquente pour un exemple.

Questions fréquentes

Qu’est-ce qui a changé depuis que Canvas Context est devenu disponible de manière générale ?

Maintenant que Canvas Context est disponible de manière générale, les détails suivants s’appliquent :

• Tous les horodatages avec un type datetime provenant des propriétés d’événement déclencheur dans les Canvas basés sur des actions sont en UTC.
• Ce changement impacte tous les Canvas basés sur des actions, que le Canvas spécifique utilise une étape Context ou non.

Quelle est la raison de ce changement ?

Ce changement s’inscrit dans un effort plus large visant à créer une expérience plus prévisible et cohérente lors de la modification des étapes et des messages Canvas.

Les Canvas déclenchés par API ou planifiés sont-ils impactés par ce changement ?

Non.

Ce changement impacte-t-il les propriétés d’entrée Canvas ?

Oui, cela impacte canvas_entry_properties si la canvas_entry_property est utilisée dans un Canvas basé sur des actions et que le type de propriété est time. Dans tous les cas, nous recommandons d’utiliser les filtres Liquid time_zone pour que les horodatages soient représentés dans le fuseau horaire souhaité.

Voici un exemple de la marche à suivre :

Quel est un exemple concret de la manière dont le nouveau comportement des horodatages pourrait affecter mes messages ?

Imaginons un Canvas basé sur des actions contenant le contenu suivant dans une étape Message :

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Cela produit le message suivant :

1

Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!

Comme aucun fuseau horaire n’est spécifié via Liquid, l’horodatage ici est en UTC.

Pour spécifier clairement un fuseau horaire, nous pouvons utiliser les filtres Liquid time_zone comme ceci :

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Cela produit le message suivant :

1

Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!

Comme le fuseau horaire America/Los Angeles est spécifié via Liquid, l’horodatage ici est en PST.

Le fuseau horaire préféré peut également être envoyé dans le payload des propriétés d’événement et utilisé dans la logique Liquid :

1
2
3
4

{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

En quoi les variables de contexte diffèrent-elles des propriétés d’entrée Canvas ?

Les propriétés d’entrée Canvas sont incluses en tant que variables de contexte Canvas. Cela signifie que vous pouvez envoyer des propriétés d’entrée Canvas via l’API Braze et les référencer dans d’autres étapes, de manière similaire à l’utilisation d’une variable de contexte avec l’extrait de code Liquid.

Les variables peuvent-elles se référencer mutuellement dans une même étape Context ?

Oui. Toutes les variables d’une étape Context sont évaluées en séquence, ce qui signifie que vous pourriez avoir les variables de contexte suivantes configurées :

Cela s’applique également à travers plusieurs étapes Context. Par exemple, imaginez la séquence suivante :

1. Une étape Context initiale crée une variable appelée JobInfo avec la valeur job_title.
2. Une étape Message référence {{context.${JobInfo}}} et affiche job_title à l’utilisateur.
3. Plus tard, une étape Context met à jour la variable de contexte, changeant la valeur de JobInfo en job_description.
4. Toutes les étapes suivantes qui référencent JobInfo utilisent désormais la valeur mise à jour job_description.

Les variables de contexte utilisent leur valeur la plus récente tout au long du Canvas, chaque mise à jour affectant toutes les étapes suivantes qui référencent cette variable.