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.

Important

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.

Comment ça fonctionne

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 ni 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. Cela les rend idéales pour les informations temporaires qui ne sont pertinentes que pour une campagne ou un flux de travail 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.

Au sein d’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 programmée d’un utilisateur, puis l’utiliser pour définir des délais personnalisés et envoyer des rappels.

Vous pouvez définir les variables de contexte de deux façons :

• À 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 les variables de contexte manuellement 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 vers New York tout en envoyant des mises à jour différentes concernant son vol de 8 h vers 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 des 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 séquentiellement.

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 séquentiellement, de sorte qu’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 est terminé.
• 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 se traitent 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 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 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

Si le filtre Context Variable est disponible 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 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. Écrivez manuellement une expression Liquid ou utilisez Ajouter une personnalisation pour créer un extrait de code Liquid à partir d’attributs 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, 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 le sélectionner dans le menu déroulant de l’éditeur d’étape. Pour un guide complet, 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 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 stocke sa sortie dans le contexte du Canvas, que vous pouvez évaluer à l’aide de 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 la 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évisualisation des 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 sont évaluées selon 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 ne se standardise pas 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 utilisateurs à la place.

Veillez à observer les scénarios courants susceptibles de créer des variables de contexte invalides. Lors de la prévisualisation de 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. Cependant, 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).
• L’expression Liquid appelle {% abort_message() %}.

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

• L’utilisateur avance à l’étape suivante.
• L’analyse de l’étape du Canvas comptabilise 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 correctement à jour. Si la variable de contexte est non valide, vos utilisateurs peuvent continuer dans votre Canvas au-delà de l’étape de contexte, mais peuvent ne pas être éligibles aux étapes suivantes.

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

Une variable de contexte peut également être volontairement ignorée avec abort_message. Voir 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 de contexte, abort_message n’affecte que la variable dans laquelle il se trouve. Il n’arrête pas l’étape et ne fait pas sortir l’utilisateur du Canvas.

Lorsque le 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 de contexte précédente a déjà défini cette variable, l’utilisateur conserve la valeur précédente.
• Les autres variables de l’étape sont toujours évaluées et définies.
• Les variables suivantes dans la même étape qui font référence à cette variable ne reçoivent pas de nouvelle valeur de celle-ci.
• L’utilisateur avance à l’étape suivante.
• L’analyse de l’étape du Canvas comptabilise la variable comme Not Updated.

Par exemple, cette variable est définie sur true pour les utilisateurs en France et ignorée pour tous les autres :

1
2
3
4
5

{% if ${country} == "France" %}
  true
{% else %}
  {% abort_message("Not in France") %}
{% endif %}

Lorsque vous prévisualisez les parcours utilisateurs, une variable ignorée apparaît sous la forme « variable_name was not updated because the Liquid logic triggered an abort ».

Si des étapes ultérieures dépendent de cette variable, prévoyez les utilisateurs pour lesquels elle n’est pas définie. Par exemple, vous pouvez les orienter à l’aide d’une étape de parcours d’audience.

Remarque

Les abandons d’étapes de contexte ne sont pas enregistrés dans le journal d’activité des messages, et la raison que vous transmettez à abort_message n’est pas affichée.

Délais d’envoi avec le contenu connecté

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

Comportement de réessai

Les appels de contenu connecté dans un Canvas ne sont réessayés que lorsque l’appel inclut :retry.

• Étapes de contexte et de mise à jour utilisateur : Braze réessaie l’appel de contenu connecté au niveau de l’étape (jusqu’à cinq fois). Si chaque réessai échoue, l’utilisateur sort du Canvas.
• Étapes de message : Le contenu connecté avec :retry utilise toujours le pipeline de messaging. Les destinataires sont retardés dans la file d’attente d’envoi pendant que Braze réessaie l’appel jusqu’à cinq fois. Si chaque réessai échoue, le message est abandonné et l’utilisateur avance à l’étape suivante.

Pour les étapes de contexte et de mise à jour utilisateur, certaines erreurs d’étape réessayables — telles qu’un échec de récupération de code promotionnel ou une erreur d’étape inattendue — peuvent déclencher des réessais 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 Réessais 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 de contenu connecté (et son temps de réponse)
• La taille du lot (par défaut 1 000 utilisateurs par lot)

Si votre endpoint de contenu connecté a des limites de débit, gardez à l’esprit que les étapes de contexte traitent les utilisateurs de manière séquentielle au sein de chaque lot, ce qui aide à 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.

Cohérence des fuseaux horaires

Pour les espaces de travail avec 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 comportement s’applique que le Canvas utilise ou non une étape Context.

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

Comment Canvas Context affecte-t-il les horodatages ?

Pour les espaces de travail avec Canvas Context :

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

Quelle est la raison de ce changement ?

Ce changement s’inscrit dans un effort plus large pour 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 affecte-t-il les propriétés d’entrée Canvas ?

Oui, cela affecte les canvas_entry_properties si la canvas_entry_property est utilisée dans un Canvas basé sur les 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 que nous avons un Canvas basé sur les actions qui contient 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é avec Liquid, l’horodatage est ici 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é avec Liquid, l’horodatage est ici 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 seule étape Context ?

Oui. Toutes les variables d’une étape Context sont évaluées de manière séquentielle, ce qui signifie que vous pourriez configurer les variables de contexte suivantes :

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.