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.

La disponibilité de Canvas Context varie selon l’espace de travail. Si Contexte n’apparaît pas dans le menu des étapes Canvas et que le menu de personnalisation affiche Canvas Entry Properties au lieu de Variables de contexte, utilisez canvas_entry_properties pour les données d’entrée. Contactez votre gestionnaire de compte si vous avez besoin d’accéder à Canvas Context.
Fonctionnement

Les étapes 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 qu’au sein de ce parcours Canvas et ne sont pas conservées d’un Canvas à l’autre ni en dehors de la session.
Les variables de contexte n’existent que pour ce parcours Canvas précis. Elles ne modifient pas durablement le profil utilisateur et n’apparaissent pas dans les autres Canvas. Elles sont donc idéales pour stocker des informations temporaires qui ne concernent qu’une campagne ou un flux de travail spécifique.

Pour une référence complète sur les variables de contexte, notamment les types de données, leur utilisation et les bonnes pratiques, consultez la Référence des variables de contexte.
Dans une étape Contexte, vous pouvez définir ou mettre à jour jusqu’à 10 variables de contexte. Ces variables permettent de personnaliser les délais, de segmenter les utilisateurs de manière dynamique et d’enrichir vos messages tout au long du Canvas. Par exemple, vous pouvez 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 dans le 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 Contexte : Définissez ou mettez à jour manuellement des variables de contexte en ajoutant une étape 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 Ajouter une personnalisation). Une fois définies, vous pouvez référencer les variables de contexte dans tout le 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 la liste déroulante 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, les variables de contexte sont redéfinies en fonction des données d’entrée les plus récentes et de la configuration du Canvas. Les utilisateurs peuvent ainsi avoir plusieurs parcours actifs, chacun avec son propre contexte. Par exemple, si un client a deux vols à venir, il aura deux états de parcours distincts exécutés simultanément—chacun avec ses propres variables de contexte propres au vol, comme l’heure de départ et la destination. Vous pouvez ainsi envoyer des rappels personnalisés concernant son vol de 14 h pour New York, tout en envoyant d’autres mises à jour sur son vol de 8 h pour Los Angeles demain, afin que chaque message reste pertinent pour la réservation concernée.
Traitement des utilisateurs et traitement par lots
Les étapes Contexte traitent les utilisateurs par lots afin d’optimiser les performances. Lorsque des utilisateurs entrent dans une étape Contexte, Braze les traite par défaut par lots de 1 000 utilisateurs. Ces lots sont traités en parallèle, mais au sein de chaque lot, les utilisateurs sont traités de manière séquentielle.
Concrètement :
Exemple : Si 3 500 utilisateurs entrent dans une étape Contexte comportant 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 : un lot de 1 000 utilisateurs prend donc environ 10,8 minutes (650 secondes ; 1 000 × 650 ms).
- Les lots se terminent à des moments différents, si bien que les utilisateurs passent 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, selon la taille des lots et les temps de réponse du contenu connecté.
Sans contenu connecté, les étapes Contexte sont traitées beaucoup plus rapidement, car il n’y a aucun appel d’API externe à attendre.
Points à prendre en compte
- Vous pouvez définir jusqu’à 10 variables de contexte par étape Contexte.
- Chaque variable doit porter un nom unique (lettres, chiffres et traits de soulignement 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 Contexte ; redéfinir une variable dans une étape Contexte remplace la valeur provenant de l’API.
Pour en savoir plus et découvrir des utilisations avancées, consultez la référence des variables de contexte.
Création d’une étape Contexte

Si Context Variable est disponible comme filtre dans votre espace de travail, vous n’avez pas besoin d’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. 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 choisissez Contexte.
Étape 2 : Définir les variables

Vous pouvez définir jusqu’à 10 variables de contexte pour chaque étape Contexte.
Pour définir une variable de contexte :
- Donnez un nom à votre variable de contexte.
- Sélectionnez un type de données.
- Rédigez une expression Liquid manuellement ou utilisez Ajouter une personnalisation pour créer un extrait de code Liquid à partir d’attributs existants.
- Sélectionnez Aperçu pour vérifier la valeur de votre variable de contexte.
- (Facultatif) Pour ajouter d’autres variables, sélectionnez Ajouter une variable de contexte et répétez les étapes 1 à 4.
- Lorsque vous avez terminé, sélectionnez Terminé.
Vous pouvez désormais utiliser votre variable de contexte partout où vous utilisez Liquid, par exemple 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 la liste déroulante de l’éditeur d’étape. Pour une présentation complète, consultez la référence des variables de contexte.

Lorsque vous faites référence à des variables de contexte, utilisez toujours le format {{context.${variable_name}}}.
Filtres de variables de contexte
Vous pouvez créer des filtres à l’aide de 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 enregistre sa sortie dans le contexte du Canvas, que vous pouvez ensuite é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 plutôt que le seul nom de la variable de premier niveau (par exemple, intent_agent.persona lorsque persona est imbriqué sous intent_agent).

La liste Nom de la variable de contexte inclut les variables issues des étapes Contexte et des étapes Agent. Pour une propriété d’entrée du Canvas, saisissez son nom et sélectionnez Utiliser « ENTRY_PROPERTY_NAME ». Remplacez ENTRY_PROPERTY_NAME par le nom de la propriété d’entrée que vous avez saisi. Pour une propriété imbriquée, utilisez la notation par points, comme order.total.
Pour la configuration des filtres, la logique de comparaison et des exemples avancés, consultez la référence des variables de contexte.

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 utilisateurs
Nous vous recommandons de tester et de prévisualiser vos parcours utilisateurs pour vous assurer que vos messages sont envoyés à la bonne audience et que les variables de contexte aboutissent aux résultats attendus.

Si vous prévisualisez votre Canvas dans la section Aperçu et test d’envoi de l’éditeur, l’horodatage de l’aperçu du message de test n’est pas converti en UTC, car ce panneau génère les aperçus sous forme de chaînes de caractères. Ainsi, si un Canvas est configuré pour accepter un objet time, l’aperçu du message ne reflète pas fidèlement ce qui se passe lorsque le Canvas est en ligne. Pour tester votre Canvas de la manière la plus précise possible, nous vous recommandons plutôt de prévisualiser les parcours utilisateurs.
Pensez à repérer les scénarios courants qui génèrent des variables de contexte non valides. Lorsque vous prévisualisez votre parcours utilisateur, vous pouvez consulter les résultats des étapes de délai personnalisées qui utilisent des variables de contexte, ainsi que toutes les comparaisons effectuées dans les étapes d’audience ou de décision qui associent les utilisateurs à des variables de contexte.
Si la variable de contexte est valide, vous pouvez la référencer dans l’ensemble de votre Canvas. En revanche, 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 Contexte pour attribuer une heure de rendez-vous aux utilisateurs et que vous définissez une date passée comme valeur de cette heure de rendez-vous, l’e-mail de rappel de votre étape Message ne sera pas envoyé.
Conversion des chaînes de caractères du contenu connecté en JSON
Lorsque vous effectuez un appel de contenu connecté dans une étape Contexte, le JSON renvoyé par l’appel est évalué comme une chaîne de caractères, par souci de cohérence et pour éviter les erreurs. Pour convertir cette chaîne en JSON, utilisez as_json_string. Par exemple :
{% 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).
- L’expression Liquid appelle
{% abort_message() %}.
Par exemple, si le type de données de la variable de contexte est Nombre mais que l’expression Liquid renvoie une chaîne de caractères, la variable n’est pas valide.
Dans ces situations :
- L’utilisateur passe à l’étape suivante.
- L’analyse de l’étape du Canvas comptabilise ce cas comme Non mis à jour.
Lors de la résolution des problèmes, surveillez l’indicateur Non mis à jour pour vérifier que votre variable de contexte se met à jour correctement. Si la variable de contexte n’est pas valide, vos utilisateurs peuvent continuer dans votre Canvas au-delà de l’étape Contexte, mais risquent de ne pas être éligibles aux étapes suivantes.
Consultez la section Types de données pour obtenir des exemples de configuration pour chaque type de données.
Une variable de contexte peut aussi être ignorée volontairement avec abort_message. Consultez Utiliser abort_message dans une variable de contexte.
Utiliser abort_message dans une variable de contexte
Vous pouvez utiliser l’étiquette Liquid abort_message dans la valeur d’une variable de contexte pour ignorer cette variable pour certains utilisateurs. Dans une étape Contexte, abort_message n’affecte que la variable dans laquelle elle se trouve. Elle n’interrompt pas l’étape et ne fait pas sortir l’utilisateur du Canvas.
Lorsque le code Liquid d’une variable de contexte appelle abort_message pour un utilisateur :
- La variable n’est pas définie pour cet utilisateur. Si une étape Contexte antérieure avait déjà défini cette variable, l’utilisateur conserve cette valeur précédente.
- Les autres variables de l’étape sont tout de même évaluées et définies.
- Les variables suivantes de la même étape qui font référence à cette variable ne reçoivent pas de nouvelle valeur de sa part.
- L’utilisateur passe à l’étape suivante.
- L’analyse de l’étape du Canvas comptabilise la variable comme Non mis à jour.
Par exemple, cette variable est définie sur true pour les utilisateurs situés en France et ignorée pour tous les autres :
{% if ${country} == "France" %}
true
{% else %}
{% abort_message("Not in France") %}
{% endif %}
Lorsque vous prévisualisez les parcours utilisateurs, une variable ignorée s’affiche sous la forme « variable_name n’a pas été mise à jour, car la logique Liquid a déclenché un abandon ».
Si des étapes ultérieures dépendent de cette variable, prévoyez le cas des utilisateurs pour lesquels elle n’est pas définie. Par exemple, vous pouvez les orienter à l’aide d’une étape Parcours d’audience.

Les abandons dans les étapes Contexte ne sont pas enregistrés dans le journal d’activité des messages, et le motif que vous transmettez à abort_message n’est pas affiché.
Retards d’envoi avec le contenu connecté
Tous les utilisateurs d’un lot sont traités avant que l’un d’entre eux ne progresse. Une fois le traitement du lot terminé, les utilisateurs traités avec succès passent à l’étape suivante, tandis que ceux en échec font l’objet de nouvelles tentatives séparément : les utilisateurs traités avec succès n’attendent pas la réussite des nouvelles tentatives pour 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 Contexte et Mise à jour de l’utilisateur : Braze relance l’appel de contenu connecté au niveau de l’étape (jusqu’à cinq fois). Si toutes les nouvelles tentatives échouent, l’utilisateur sort du Canvas.
- Étapes Message : le contenu connecté avec
:retrypasse toujours par le pipeline d’envoi de messages. Les destinataires sont mis en attente dans la file d’envoi pendant que Braze relance l’appel jusqu’à cinq fois. Si toutes les nouvelles tentatives échouent, le message est interrompu et l’utilisateur passe à l’étape suivante.
Pour les étapes Contexte et 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 sortir l’utilisateur du Canvas.
Pour plus d’informations sur l’étiquette :retry, consultez Nouvelles tentatives du contenu connecté.
Le temps nécessaire pour traiter tous les utilisateurs d’une étape Contexte dépend des éléments suivants :
- Le nombre d’utilisateurs qui entrent 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é est soumis à des limites de débit, gardez à l’esprit que les étapes Contexte traitent les utilisateurs de manière séquentielle au sein de chaque lot, ce qui aide naturellement à respecter ces limites. Cependant, plusieurs lots sont traités en parallèle : assurez-vous donc que votre endpoint peut gérer des requêtes simultanées provenant de plusieurs lots.
Cohérence des fuseaux horaires
Pour les espaces de travail qui utilisent Canvas Context, toutes les propriétés d’événement d’horodatage par défaut dans les Canvas basés sur des actions sont exprimées en UTC. Ce comportement s’applique, que le Canvas utilise ou non une étape Contexte.

Dans tous les cas, nous vous recommandons vivement d’utiliser les filtres Liquid time_zone pour que les horodatages s’affichent dans le fuseau horaire souhaité. Consultez cette question fréquente pour voir un exemple.
Foire aux questions
Quel est l’impact de Canvas Context sur les horodatages ?
Pour les espaces de travail qui utilisent Canvas Context :
- Tous les horodatages de type datetime issus des propriétés de l’événement déclencheur dans les Canvas basés sur des actions sont exprimés en UTC.
- Ce changement concerne tous les Canvas basés sur des actions, qu’ils utilisent ou non une étape Contexte.
Pourquoi ce changement ?
Ce changement s’inscrit dans une démarche plus large visant à rendre la modification des étapes et des messages du Canvas plus prévisible et plus cohérente.
Les Canvas déclenchés par API ou planifiés sont-ils concernés par ce changement ?
Non.
Ce changement a-t-il un impact sur les propriétés d’entrée du Canvas ?
Oui, il concerne 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 vous recommandons d’utiliser les filtres Liquid time_zone pour afficher les horodatages dans le fuseau horaire souhaité.
Voici un exemple :
| Liquid dans l’étape Message | Résultat | Est-ce la bonne façon de représenter les fuseaux horaires dans Liquid ? |
|---|---|---|
{{canvas_entry_properties.${timestamp_property}}} |
2025-08-05T08:15:30:250-0800 |
Non |
{{canvas_entry_properties.${timestamp_property} | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 4:15pm |
Non |
{{canvas_entry_properties.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 8:15am |
Oui |
Pouvez-vous donner un exemple concret de l’impact du nouveau comportement des horodatages sur mes messages ?
Imaginons un Canvas basé sur des actions dont l’étape Message contient le texte suivant :
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!
On obtient alors le message suivant :
Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!
Comme aucun fuseau horaire n’est spécifié avec Liquid, l’horodatage est ici exprimé en UTC.
Pour indiquer clairement un fuseau horaire, vous pouvez utiliser les filtres Liquid time_zone comme ceci :
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!
On obtient alors le message suivant :
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é avec Liquid, l’horodatage est ici exprimé en heure du Pacifique (PST).
Le fuseau horaire préféré peut également être envoyé dans le payload des propriétés de l’événement, puis utilisé dans la logique Liquid :
{
"appointment_time": "2025-08-05T08:15:30:250-0800"
"user_timezone": "America/Los_Angeles"
}
Quelle est la différence entre les variables de contexte et les propriétés d’entrée du Canvas ?
Les propriétés d’entrée du Canvas sont incluses en tant que variables de contexte du Canvas. Vous pouvez donc envoyer des propriétés d’entrée du Canvas via l’API de Braze et y faire référence dans d’autres étapes, comme vous le feriez avec une variable de contexte dans un extrait de code Liquid.
Les variables peuvent-elles faire référence les unes aux autres au sein d’une même étape Contexte ?
Oui. Toutes les variables d’une étape Contexte sont évaluées dans l’ordre, ce qui signifie que vous pouvez configurer les variables de contexte suivantes :
| Variable de contexte | Valeur | Description |
|---|---|---|
favorite_cuisine |
{{custom_attribute.${Favorite Cuisine}}} |
Le type de cuisine préféré d’un utilisateur. |
promo_code |
EATFRESH |
Le code de réduction disponible pour un utilisateur. |
personalized_message |
"Enjoy a discount of" {{context.${promo_code}}} "on delivery from your favorite" {{context.${favorite_cuisine}}} restaurants!" |
Un message personnalisé qui combine les variables précédentes. Dans une étape Message, vous pouvez utiliser l’extrait de code Liquid {{context.${personalized_message}}} pour faire référence à la variable de contexte et envoyer un message personnalisé à chaque utilisateur. Vous pouvez aussi utiliser une étape Contexte pour enregistrer la valeur du code promotionnel et l’intégrer dans d’autres étapes de votre Canvas. |
Ce principe s’applique également à plusieurs étapes Contexte. Prenons par exemple la séquence suivante :
- Une première étape Contexte crée une variable appelée
JobInfoavec la valeurjob_title. - Une étape Message fait référence à
{{context.${JobInfo}}}et affichejob_titleà l’utilisateur. - Plus loin, une étape Contexte met à jour la variable de contexte et remplace la valeur de
JobInfoparjob_description. - Toutes les étapes suivantes qui font référence à
JobInfoutilisent désormais la valeur mise à jourjob_description.
Les variables de contexte utilisent leur valeur la plus récente tout au long du Canvas : chaque mise à jour s’applique à toutes les étapes suivantes qui font référence à cette variable.