Variables de contexte

Les variables de contexte sont des données temporaires que vous pouvez créer et utiliser au cours du parcours d’un utilisateur dans un Canvas spécifique. Elles vous permettent de personnaliser les délais, de segmenter les utilisateurs de manière dynamique et d’enrichir les messages sans modifier de façon permanente les informations du profil utilisateur. Les variables de contexte n’existent que dans la session du Canvas et ne persistent pas entre différents Canvas ni en dehors de la session.

Fonctionnement des variables de contexte

Les variables de contexte peuvent être définies de deux manières :

• À l’entrée du Canvas : Lorsque les utilisateurs entrent dans un Canvas, les données provenant de l’événement ou du déclencheur API peuvent automatiquement alimenter les variables de contexte.
• Dans une étape de contexte : Vous pouvez définir ou mettre à jour manuellement les variables de contexte à l’intérieur du Canvas en ajoutant une étape de contexte.

Chaque variable de contexte comprend :

• Un nom (tel que flight_time ou subscription_renewal_date)
• Un type de données (tel que nombre, chaîne de caractères, heure ou tableau)
• Une valeur que vous attribuez à l’aide de Liquid ou via l’outil Add Personalization.

Une fois définie, vous pouvez utiliser une variable de contexte dans l’ensemble du Canvas en la référençant dans ce format : {{context.${example_variable_name}}}.

Par exemple, {{context.${flight_time}}} pourrait renvoyer l’heure de vol prévue de l’utilisateur.

Chaque fois qu’un utilisateur entre dans le Canvas, même s’il y est déjà entré auparavant, les variables de contexte sont redéfinies en fonction des dernières données d’entrée et de la configuration du Canvas. Cette approche avec état permet à chaque entrée dans le Canvas de conserver son propre contexte indépendant, ce qui permet aux utilisateurs d’avoir plusieurs états actifs au sein du même parcours tout en conservant le contexte spécifique à chaque état.

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, de sorte que chaque message reste pertinent par rapport à la réservation spécifique.

Considérations

Vous pouvez définir jusqu’à 10 variables de contexte par étape de contexte. Chaque nom de variable peut contenir jusqu’à 100 caractères et ne doit utiliser que des lettres, des chiffres ou des underscores.

Les définitions de variables de contexte peuvent contenir jusqu’à 10 240 caractères. Si vous transmettez des variables de contexte dans un Canvas déclenché par API, elles partagent le même espace de noms que les variables créées dans une étape de contexte. Par exemple, si vous envoyez une variable purchased_item dans l’objet de contexte de l’endpoint /canvas/trigger/send, vous pouvez la référencer avec {{context.${purchased_item}}}. Si vous redéfinissez cette variable dans une étape de contexte, la nouvelle valeur remplacera la valeur de l’API pour le parcours de cet utilisateur.

Vous pouvez stocker jusqu’à 50 Ko par étape de contexte, répartis sur un maximum de 10 variables. Si la taille totale de toutes les variables d’une étape dépasse 50 Ko, les variables qui dépassent la limite ne seront ni évaluées ni stockées. Par exemple, si vous avez trois variables dans une étape de contexte :

• Variable 1 : 30 Ko
• Variable 2 : 19 Ko
• Variable 3 : 2 Ko

La variable 3 ne sera ni évaluée ni stockée, car la somme des variables précédentes dépasse 50 Ko.

Types de données

Les variables de contexte créées ou mises à jour dans l’étape peuvent se voir attribuer les types de données suivants.

Remarque

Les variables de contexte ont les mêmes formats attendus pour les types de données que les propriétés d’événement.

Lorsque vous utilisez le type tableau, Braze tente d’analyser la valeur en JSON, ce qui permet de créer des tableaux d’objets avec succès. Si les objets contenus dans vos tableaux ne sont pas du JSON valide, le résultat sera un simple tableau de chaînes de caractères.

Pour les objets imbriqués et les tableaux d’objets, utilisez le filtre Liquid as_json_string. Si vous créez le même objet dans une étape de contexte, vous devrez rendre l’objet en utilisant as_json_string, par exemple {{context.${object_array} | as_json_string }}

Par défaut, le type de données heure est en UTC. Si vous utilisez un type de données chaîne de caractères pour stocker une valeur horaire, vous pouvez définir l’heure dans un fuseau horaire différent, comme PST.

Par exemple, si vous envoyez un message à un utilisateur la veille de son anniversaire, vous enregistreriez la variable de contexte avec le type de données heure, car il y a une logique Liquid associée à l’envoi la veille. En revanche, si vous envoyez un message pour les fêtes le jour de Noël (25 décembre), vous n’auriez pas besoin de référencer l’heure comme variable dynamique. Utiliser un type de données chaîne de caractères serait alors préférable.

Pour les types de données objet, vous pouvez utiliser la notation par points pour spécifier un chemin à travers les données. Par exemple, si votre étape de contexte définit une variable de contexte order_summary avec cette structure :

1
2
3
4
5

{
  "shipping": {
    "carrier": "overnight"
  }
}

Dans un filtre parcours d’audience ou arbre décisionnel, saisissez le chemin comme nom de variable de contexte en utilisant la notation par points (par exemple, order_summary.shipping.carrier). Lorsque le filtre est évalué, Braze résout ce chemin vers la valeur overnight.

En Liquid (par exemple dans une étape Message), utilisez {{context.${order_summary}.shipping.carrier}} à la place.

Utiliser les variables de contexte

Vous pouvez utiliser les variables de contexte partout où vous utilisez Liquid dans un Canvas, par exemple dans les étapes Message et Mise à jour de l’utilisateur, en sélectionnant Ajouter une personnalisation. Pour les messages in-app et les bannières dans les étapes Message, vous pouvez sélectionner des variables de contexte pour déterminer quand le message doit expirer.

Par exemple, imaginons que vous souhaitez informer des passagers de leur accès au salon VIP avant leur prochain vol. Ce message ne doit être envoyé qu’aux passagers ayant acheté un billet en première classe. Une variable de contexte est un moyen flexible de suivre cette information.

Les utilisateurs entreront dans le Canvas lorsqu’ils achèteront un billet d’avion. Pour déterminer l’éligibilité à l’accès au salon, nous allons créer une variable de contexte appelée lounge_access_granted dans une étape Contexte, puis référencer cette variable de contexte dans les étapes suivantes du parcours utilisateur.

Dans cette étape Contexte, nous utiliserons {{custom_attribute.${purchased_flight}}} pour déterminer si le type de vol acheté est first_class.

Ensuite, nous allons créer une étape Message pour cibler les utilisateurs pour lesquels {{context.${lounge_access_granted}}} est true. Ce message sera une notification push incluant des informations personnalisées sur le salon. En fonction de cette variable de contexte, les passagers éligibles recevront les messages pertinents avant leur vol.

• Les passagers en première classe recevront : « Profitez d’un accès exclusif au salon VIP ! »
• Les passagers en classe affaires et économique recevront : « Améliorez votre vol pour un accès exclusif au salon VIP. »

Conseil

Vous pouvez ajouter des options de délai personnalisées avec les informations de l’étape Contexte, ce qui signifie que vous pouvez sélectionner la variable qui retarde les utilisateurs.

Pour les parcours d’action et les critères de sortie

Vous pouvez tirer parti des filtres de comparaison de propriétés avec des variables de contexte ou des attributs personnalisés dans ces actions de déclenchement : Effectuer un événement personnalisé et Effectuer un achat. Ces déclencheurs d’action prennent également en charge les filtres de propriétés pour les propriétés de base et imbriquées.

• Lors de la comparaison avec des propriétés de base, les comparaisons disponibles correspondront au type de la propriété définie par l’événement personnalisé. Par exemple, les propriétés de type chaîne de caractères auront « exactement égal à » et « correspond à l’expression régulière ». Les propriétés booléennes seront vrai ou faux.
• Lors de la comparaison avec des propriétés imbriquées, les types ne sont pas prédéfinis, vous pouvez donc sélectionner des comparaisons entre plusieurs types de données pour les booléens, nombres, chaînes de caractères, heure et jour de l’année, similairement aux comparaisons pour les attributs personnalisés imbriqués. Si vous sélectionnez un type de données qui ne correspond pas au type de données réel de la propriété imbriquée au moment de la comparaison, l’utilisateur ne correspondra pas à l’étape du parcours d’action ni aux critères de sortie.

Exemples de parcours d’action

Important

Pour les comparaisons d’attributs personnalisés, nous utiliserons la valeur de l’attribut personnalisé au moment où l’action est effectuée. Cela signifie qu’un utilisateur ne correspondra pas au groupe d’actions si cet attribut personnalisé n’est pas renseigné au moment de la comparaison, ou si la valeur de l’attribut personnalisé ne correspond pas aux comparaisons de propriétés définies. C’est le cas même si l’utilisateur aurait correspondu au moment de son entrée dans l’étape du parcours d’action.

• effectuer un événement personnalisé
• effectuer un achat

Exemples de critères de sortie

• effectuer un événement personnalisé
• effectuer un achat

Définir une expiration

Pour les bannières et les messages in-app dans une étape Message d’un Canvas, sélectionnez Une durée après la disponibilité de l’étape pour l’expiration, puis activez Personnaliser la durée pour piloter la fenêtre de disponibilité à partir d’une variable de contexte — par exemple, pour correspondre à la durée d’une promotion ou d’une réservation provenant d’une étape Contexte.

Personnaliser la durée s’applique à cette option d’expiration basée sur la durée. Si vous choisissez À une date et une heure spécifiques à la place, définissez l’expiration à l’aide des contrôles de date et d’heure.

Délais des parcours d’action

Dans une étape parcours d’action, sous Fenêtre d’évaluation, activez Personnaliser le délai pour définir combien de temps les utilisateurs sont retenus dans l’étape à partir d’une variable de contexte. Utilisez cette option lorsque la période d’attente doit varier par utilisateur en fonction de détails tels que le niveau ou la région.

Filtres de variables de contexte

Vous pouvez créer des filtres qui utilisent des variables de contexte précédemment déclarées dans les étapes parcours d’audience et arbre décisionnel.

Remarque

Les filtres de variables de contexte ne sont disponibles que pour les étapes de parcours d’audience et d’arbre décisionnel.

Les variables de contexte sont déclarées et uniquement accessibles dans le cadre d’un Canvas, ce qui signifie qu’elles ne peuvent pas être référencées dans les Segments. Les filtres de variables de contexte fonctionnent de manière similaire dans les étapes de parcours d’audience et d’arbre décisionnel — les étapes de parcours d’audience représentent plusieurs groupes, tandis que les étapes d’arbre décisionnel représentent des décisions binaires.

De la même manière que les variables de contexte Canvas ont des types prédéfinis, les comparaisons entre les variables de contexte et les valeurs statiques doivent avoir des types de données correspondants. Le filtre de variable de contexte permet des comparaisons entre plusieurs types de données pour les booléens, nombres, chaînes de caractères, heure et jour de l’année, similairement aux comparaisons pour les attributs personnalisés imbriqués.

Voici un exemple de filtre de variable de contexte comparant la variable de contexte product_name à l’expression régulière /braze/.

Filtres Jour de l’année et Heure pour les variables de contexte de type date

Pour utiliser les filtres de comparaison Jour de l’année ou Heure avec une variable de contexte :

1. Ajoutez une étape Contexte qui définit une variable de contexte sur une date du calendrier (par exemple, le 23 octobre 2025).
2. Ajoutez une étape parcours d’audience après l’étape Contexte.
3. Dans l’étape de parcours d’audience, ajoutez un filtre qui répartit les utilisateurs en fonction de cette variable de contexte.
4. Choisissez une comparaison dans la catégorie Jour de l’année ou Heure.

Si une variable de contexte n’a pas de type déclaré, Braze affiche tous les types de comparaison disponibles dans le menu déroulant, y compris Jour de l’année et Heure. Si la variable est déclarée comme un type heure dans l’étape Contexte, seules les comparaisons Jour de l’année et Heure sont affichées. Pour les autres types de données avec un type connu (par exemple, un attribut personnalisé imbriqué de type heure), seules les comparaisons applicables à ce type sont affichées.

Remarque

Utilisez le même type de données pour votre variable de contexte et votre comparaison. Par exemple, si votre variable de contexte est de type heure, utilisez des comparaisons de type heure (telles que « avant » ou « après »). L’utilisation de types de données non concordants (tels que des comparaisons de chaînes de caractères avec une variable de contexte de type heure) peut entraîner un comportement inattendu.

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.

Comparer à des variables de contexte ou des attributs personnalisés

En activant le bouton Comparer à une variable de contexte ou un attribut personnalisé, vous pouvez construire des filtres de variables de contexte qui comparent avec des variables de contexte précédemment définies ou des attributs personnalisés de l’utilisateur. Cela peut être utile pour effectuer des comparaisons dynamiques par utilisateur, comme le context déclenché par API, ou pour condenser une logique de comparaison complexe définie entre plusieurs variables de contexte.

• exemple 1
• exemple 2

Standardisation de la cohérence des fuseaux horaires

Bien que la plupart des propriétés d’événement utilisant le type horodatage soient déjà en UTC dans Canvas, il existe quelques exceptions. Avec l’ajout du contexte Canvas, toutes les propriétés d’événement d’horodatage par défaut dans les Canvas basés sur des actions seront systématiquement 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 affectera tous les Canvas basés sur des actions, que le Canvas en question utilise une étape de contexte ou non.

Important

Dans tous les cas, nous recommandons vivement 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 dans l’article sur l’étape de contexte pour un exemple.

Articles connexes

• Étape de contexte
• Personnalisation et contenu dynamique avec Liquid