Passer au contenu

Variables de contexte

Les variables de contexte sont des données temporaires que vous pouvez créer et utiliser tout au long du parcours d’un utilisateur dans un Canvas donné. Elles vous permettent de personnaliser les délais, de segmenter les utilisateurs de manière dynamique et d’enrichir vos messages sans modifier durablement les informations du profil utilisateur. Les variables de contexte n’existent que pendant la session du Canvas et ne persistent ni d’un Canvas à l’autre ni en dehors de la session.

Fonctionnement des variables de contexte

Il existe deux façons de définir des variables de contexte :

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

Chaque variable de contexte comprend :

  • Un nom (par exemple flight_time ou subscription_renewal_date)
  • Un type de données (par exemple nombre, chaîne de caractères, heure ou tableau)
  • Une valeur que vous attribuez à l’aide de Liquid ou de l’outil Ajouter une personnalisation.

Une fois définie, une variable de contexte peut être utilisée dans tout le Canvas en y faisant référence au format suivant : {{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 données d’entrée les plus récentes et de la configuration du Canvas. Grâce à cette approche avec état, chaque entrée dans le Canvas conserve son propre contexte indépendant : les utilisateurs peuvent ainsi avoir plusieurs états actifs au sein d’un même parcours, chacun gardant son contexte spécifique.

Par exemple, si un client a deux vols à venir, deux états de parcours distincts s’exécutent simultanément, chacun avec ses propres variables de contexte liées 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 informations sur son vol de 8 h pour Los Angeles le lendemain. Chaque message reste donc pertinent pour la réservation concernée.

Considérations

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

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

Vous pouvez stocker jusqu’à 50 Ko par étape 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 sont ni évaluées ni stockées. Par exemple, si vous avez trois variables dans une étape Contexte :

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

La variable 3 n’est 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 recevoir les types de données suivants.

Type de données Exemple de nom de variable Exemple de valeur
Booléen loyalty_program true
Nombre credit_score 740
Chaîne de caractères product_name green_tea
Tableau favorite_products ["wireless_headphones", "smart_homehub", "fitness_tracker_swatch"]
Tableau (d’objets) pet_details [
 { "id": 1, "type": "dog", "breed": "beagle", "name": "Gus" }
 ,
 { "id": 2, "type": "cat", "breed": "calico", "name": "Gerald" }
]
Heure (en UTC) last_purchase_date 2025-12-25T08:15:30:250-0800
Objet (aplati) user_profile {
 "first_name": "{{user.first_name}}",
 "last_name": "{{user.last_name}}",
 "email": "{{user.email}}",
 "loyalty_points": {{user.loyalty_points}},
 "preferred_categories": {{user.preferred_categories}}
}

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 d’heure, vous pouvez définir l’heure dans un autre fuseau horaire, 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 une logique Liquid est associée à l’envoi la veille. En revanche, si vous envoyez un message de fête le jour de Noël (25 décembre), vous n’auriez pas besoin de référencer l’heure comme variable dynamique : le type de données chaîne de caractères serait donc préférable.

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

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

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

Dans Liquid (par exemple dans une étape Message), utilisez plutôt {{context.${order_summary}.shipping.carrier}}.

Utiliser les variables de contexte

Vous pouvez utiliser des 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 des étapes Message, vous pouvez sélectionner des variables de contexte pour déterminer à quel moment le message doit expirer.

Par exemple, imaginons que vous souhaitiez informer les 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 offre un moyen flexible de suivre cette information.

Les utilisateurs entrent dans le Canvas lorsqu’ils achètent un billet d’avion. Pour déterminer s’ils ont droit à l’accès au salon, nous allons créer une variable de contexte appelée lounge_access_granted dans une étape Contexte, puis y faire référence dans les étapes suivantes du parcours utilisateur.

Variable de contexte configurée pour savoir si un passager a droit à l’accès au salon VIP.

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

Ensuite, nous créerons une étape Message pour cibler les utilisateurs pour lesquels {{context.${lounge_access_granted}}} vaut true. Ce message sera une notification push contenant 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 en classe économique recevront : « Surclassez votre vol pour bénéficier d’un accès exclusif au salon VIP. »

Une étape Message avec différents messages à envoyer selon le type de billet d’avion acheté.

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

Vous pouvez tirer parti de la comparaison de filtres 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.

  • Lorsque vous effectuez une comparaison avec des propriétés de base, les comparaisons disponibles correspondent au type de la propriété défini par l’événement personnalisé. Par exemple, les propriétés de type chaîne de caractères proposeront « est exactement égal à » et « correspond à l’expression régulière ». Les propriétés booléennes seront vraies ou fausses.
  • Lorsque vous effectuez une comparaison avec des propriétés imbriquées, les types ne sont pas prédéfinis : vous pouvez donc sélectionner des comparaisons sur plusieurs types de données (booléens, nombres, chaînes de caractères, heure et jour de l’année), comme pour les attributs personnalisés imbriqués. Si vous sélectionnez un type de données qui ne correspond pas au type réel de la propriété imbriquée au moment de la comparaison, l’utilisateur ne correspondra pas à l’étape de parcours d’action ni aux critères de sortie.

Exemples de parcours d’action

L’étape de parcours d’action suivante est configurée pour trier les utilisateurs ayant effectué l’événement personnalisé Account_Created dont la propriété de base source correspond à la variable de contexte app_source_variable.

Exemple d’étape de parcours d’action faisant référence à une variable de contexte lors de l’exécution d’un événement personnalisé.

L’étape de parcours d’action suivante est configurée pour faire correspondre la propriété de base brand du nom de produit spécifique shoes à une variable de contexte promoted_shoe_brand.

Exemple d’étape de parcours d’action faisant référence à une variable de contexte lors d’un achat.

Exemples de critères de sortie

Les critères de sortie indiquent qu’à tout moment de son parcours dans le Canvas, l’utilisateur quittera le Canvas si :

  • Il effectue l’événement personnalisé Abandon Cart, et
  • La propriété de base Item in Cart correspond à la valeur de chaîne de caractères de la variable de contexte cart_item_threshold.

Critères de sortie configurés pour faire sortir un utilisateur s’il effectue un événement personnalisé basé sur la variable de contexte.

Les critères de sortie indiquent qu’à tout moment de son parcours dans le Canvas, l’utilisateur quittera le Canvas si :

  • Il effectue un achat spécifique pour le nom de produit « book », et
  • La propriété imbriquée « loyalty_program » de cet achat est égale à l’attribut personnalisé « VIP » de l’utilisateur.

Critères de sortie configurés pour faire sortir un utilisateur s’il effectue un achat.

Définir une expiration

Pour les bannières et les messages in-app d’une étape Message de Canvas, sélectionnez Une durée après que l’étape est disponible pour l’expiration, puis activez Personnaliser la durée afin de déterminer la fenêtre de disponibilité à partir d’une variable de contexte, par exemple pour l’aligner sur la durée d’une promotion ou d’une réservation définie dans une étape Contexte.

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

Délais des parcours d’action

Dans une étape de parcours d’action, sous Fenêtre d’évaluation, activez Personnaliser le délai pour définir, à partir d’une variable de contexte, la durée pendant laquelle les utilisateurs restent dans l’étape. Utilisez cette option lorsque la période d’attente doit varier d’un utilisateur à l’autre en fonction de critères tels que le niveau ou la région.

Filtres de variables de contexte

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

La liste Nom de la variable de contexte comprend les variables issues des étapes Contexte et des étapes Agent. Pour une propriété d’entrée de 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, par exemple order.total.

Les variables de contexte sont déclarées et accessibles uniquement dans le périmètre d’un Canvas : elles ne peuvent donc pas être référencées dans des 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.

Exemple d’étape d’arbre décisionnel avec l’option de créer un filtre basé sur une variable de contexte.

De la même manière que les variables de contexte de Canvas ont des types prédéfinis, les comparaisons entre variables de contexte et valeurs statiques doivent avoir des types de données correspondants. Le filtre de variable de contexte permet d’effectuer des comparaisons sur plusieurs types de données (booléens, nombres, chaînes de caractères, heure et jour de l’année), comme 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/.

Configuration d’un filtre pour que la variable de contexte « product_name » corresponde à 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 de 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 de 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 connus (par exemple, un attribut personnalisé imbriqué de type heure), seules les comparaisons applicables à ce type sont affichées.

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

En activant l’option Comparer à une variable de contexte ou à un attribut personnalisé, vous pouvez créer des filtres de variables de contexte qui effectuent une comparaison avec des variables de contexte définies précédemment ou avec des attributs personnalisés de l’utilisateur. Cela peut être utile pour effectuer des comparaisons dynamiques propres à chaque utilisateur, comme le context déclenché par API, ou pour condenser une logique de comparaison complexe répartie sur plusieurs variables de contexte.

Imaginons que vous souhaitiez envoyer un rappel personnalisé aux utilisateurs après une période d’inactivité dynamique : toute personne ne s’étant pas connectée à votre application au cours des trois derniers jours doit recevoir un message.

Vous disposez d’une variable de contexte re_engagement_date définie comme {{now | minus: 3 | append: ' days'}}. Notez que 3 days peut être une valeur variable, également stockée dans un attribut personnalisé de l’utilisateur. Ainsi, si re_engagement_date est postérieure à last_login_date (stockée en tant qu’attribut personnalisé dans le profil utilisateur), l’utilisateur recevra un message.

Configuration d’un filtre utilisant les attributs personnalisés comme type de personnalisation, pour la variable de contexte « re_engagement_date » postérieure à l’attribut personnalisé « last_login_date ».

Le filtre suivant vérifie que la variable de contexte reminder_date est antérieure à la variable de contexte appointment_deadline. Cela peut aider à regrouper les utilisateurs dans une étape de parcours d’audience afin de déterminer s’ils doivent recevoir des rappels supplémentaires avant la date limite de leur rendez-vous.

Configuration d’un filtre utilisant les variables de contexte comme type de personnalisation, pour la variable de contexte « reminder_date » par rapport à la variable de contexte « appointment_deadline ».

Uniformisation des fuseaux horaires

Dans Canvas, la plupart des propriétés d’événement de type horodatage sont déjà exprimées en UTC, mais il existe quelques exceptions. Avec l’ajout du contexte Canvas, toutes les propriétés d’événement d’horodatage par défaut des Canvas basés sur l’action seront systématiquement en UTC. 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. Ce changement concerne tous les Canvas basés sur l’action, qu’ils utilisent ou non une étape Contexte.

New Stuff!