Contexte

Les étapes du canvas vous permettent de créer et de mettre à jour une ou plusieurs variables pour un utilisateur au fur et à mesure qu’il se déplace dans un canvas. Par exemple, si vous avez un Canvas qui gère les remises saisonnières, vous pouvez utiliser une variable de contexte pour stocker un code de remise différent chaque fois qu’un utilisateur entre dans le Canvas.

Comment cela fonctionne-t-il ?

!Une étape du Contexte comme première étape d’un Canvas.](/docs/fr/assets/img/context_step3.png?fa6617cfab3adb369b499fdc7aa9d553){: style=”float:right;max-width:40%;margin-left:15px;”}

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

Dans ce cadre, chaque étape Contexte peut définir plusieurs variables de contexte - des données temporaires qui vous permettent de personnaliser les délais, de segmenter les utilisateurs de manière dynamique et d’enrichir les envois sans modifier de manière permanente les informations de profil de l’utilisateur.

Par exemple, si vous gérez des réservations de vols, vous pouvez créer une variable contextuelle pour l’heure de vol planifiée de chaque utilisateur. Vous pourriez alors définir des délais par rapport à l’heure de vol de chaque utilisateur et envoyer des rappels personnalisés à partir du même Canvas.

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

• A l’entrée de la toile : Lorsque les utilisateurs entrent dans un Canvas, les données 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 des variables de contexte manuellement dans le canvas en ajoutant une étape Contexte.

Chaque variable contextuelle comprend

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

Une fois définie, vous pouvez utiliser une variable contextuelle dans l’ensemble du canvas en y faisant référence sous la forme suivante : {{context.${example_variable_name}}}.

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

Chaque fois qu’un utilisateur entre dans le canvas - même s’il l’a déjà fait auparavant - les variables contextuelles seront redéfinies en fonction des dernières données d’entrée et de la configuration du canvas. Cette approche par état permet à chaque entrée de Canvas de conserver son propre contexte indépendant, ce qui permet aux utilisateurs d’avoir plusieurs états actifs au sein d’un 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 en cours d’exécution 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 sur leur vol de 14 heures pour New York tout en envoyant des mises à jour différentes sur leur vol de 8 heures pour Los Angeles demain, de sorte que chaque message reste pertinent pour la réservation spécifique.

Considérations

• Vous pouvez avoir jusqu’à 10 variables de contexte par étape de contexte.
• Chaque nom de variable contextuelle peut comporter jusqu’à 100 caractères.
• Les noms des variables contextuelles doivent être des identifiants valides (lettres, chiffres, caractères de soulignement uniquement).
• Les définitions des variables contextuelles peuvent comporter jusqu’à 10 240 caractères.
• Les variables de contexte transmises dans un canevas déclenché par une API partagent les mêmes espaces de noms que les variables de contexte créées dans une étape du canevas. Cela signifie que si vous envoyez une variable purchased_item dans l’objet contextuel de l’endpoint /canvas/trigger/send, elle peut être référencée en tant que {context.${purchased_item}}, et la redéclaration de cette variable dans une étape du canvas remplacera ce qui a été envoyé précédemment.
• Vous pouvez stocker jusqu’à 50 Ko par pas de contexte, répartis jusqu’à 10 variables par pas. Les variables dont la taille totale dépasse 50 Ko en une seule étape ne seront pas évaluées ni stockées pour l’utilisateur. Ces tailles sont calculées l’une après l’autre. Par exemple, si vous avez 3 variables dans une étape Contexte :
  • Variable 1 : 30 KB
  • Variable 2 : 19 KB
  • Variable 3 : 2 KB
  • Cela signifie que la variable 3 ne sera pas évaluée ou stockée parce que la somme de toutes les autres variables contextuelles dépasse 50 Ko.

Création d’une étape contextuelle

Étape 1 : Ajouter une étape

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

Étape 2 : Définir les variables

Pour définir une variable de contexte :

1. Donnez un nom à votre variable contextuelle.
2. Sélectionnez un type de données.
3. Rédigez manuellement une expression Liquid 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 contextuelle.
5. (Facultatif) Pour ajouter des variables, sélectionnez Ajouter une variable contextuelle et répétez les étapes 1 à 4.
6. Lorsque vous avez terminé, sélectionnez Terminé.

Vous pouvez désormais utiliser votre variable contextuelle partout où vous utilisez Liquid, comme dans les étapes Message et Mise à jour utilisateur, en sélectionnant Ajouter une personnalisation. Pour une présentation complète, voir Utilisation des variables de contexte.

Types de données des variables contextuelles

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

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

Par exemple, si vous envoyez un message à un utilisateur la veille de son anniversaire, vous enregistrerez la variable contextuelle en tant que type de données temporel, car la logique liquide est associée à l’envoi la veille. Toutefois, si vous envoyez un message de vacances le jour de Noël (25 décembre), vous n’aurez pas besoin de référencer l’heure en tant que variable dynamique. Il est donc préférable d’utiliser un type de données de type chaîne de caractères.

Utilisation de variables contextuelles

Par exemple, supposons 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 de première classe. Une variable de contexte est un moyen souple de suivre ces informations.

Les utilisateurs entreront dans la toile lorsqu’ils achèteront un billet d’avion. Pour déterminer l’admissibilité à l’accès au salon, nous créerons une variable contextuelle appelée lounge_access_granted dans une étape Contexte, puis nous ferons référence à cette variable contextuelle dans les étapes suivantes du parcours de l’utilisateur.

Une variable contextuelle a été mise en place pour déterminer si un passager a droit à l’accès au salon VIP.](/docs/fr/assets/img/context_example4.png?f71b608b02ecedd9f0ba25b358fe35d3){: style=”max-width:90%”}

Dans cette étape du Contexte, nous utiliserons {{custom_attribute.${purchased_flight}}} pour déterminer si le type de vol qu’ils ont 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 qui comprendra des informations personnalisées sur le salon. En fonction de cette variable contextuelle, les passagers éligibles recevront les messages pertinents avant leur vol.

• Les passagers du billet de première classe recevront “Profitez d’un accès exclusif au salon VIP !
• Les passagers de la classe affaires et de la classe économique recevront “Surclassez votre vol pour bénéficier d’un accès exclusif au salon VIP.

!Une étape de message avec différents messages à envoyer, selon le type de billet d’avion acheté.](/docs/fr/assets/img/context_example3.png?e77c583305de52bab873505ba00d71ae){: style=”max-width:90%”}

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

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

• Lors de la comparaison avec les propriétés de base, les comparaisons disponibles correspondront au type de propriété défini par l’événement personnalisé. Par exemple, les propriétés de chaînes de caractères auront des correspondances d’expression régulière exactement égales. Les propriétés booléennes seront vraies ou fausses.
• 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, les nombres, les chaînes de caractères, l’heure et le jour de l’année, comme pour les comparaisons avec des 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 au parcours d’action ou aux critères de sortie.

Exemples de parcours d’action

• perform custom event
• make purchase

Exemples de critères de sortie

• perform custom event
• make purchase

Filtres de variables contextuelles

Vous pouvez créer des filtres qui utilisent des variables de contexte préalablement déclarées dans les étapes Parcours d’audience et Arbre décisionnel.

Les variables de contexte sont déclarées et accessibles uniquement dans la portée d’un Canvas, ce qui signifie qu’elles ne peuvent pas être référencées dans des segments. Les filtres d’audience fonctionnent de la même manière dans les parcours d’audience et les étapes décisionnelles. Les parcours d’audience représentent des groupes multiples, tandis que les étapes décisionnelles représentent des décisions binaires.

!Exemple d’étape décisionnelle avec la possibilité de créer un filtre avec une variable contextuelle.](/docs/fr/assets/img/context_decision_split.png?2b0b9149335a2ac917d26eadd79d37c4){: style=”max-width:90%;”}

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

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

!Configuration d’un filtre pour la variable contextuelle “product_name” correspondant à l’expression régulière “/braze/”.

Comparaison avec des variables de contexte ou des attributs personnalisés

En basculant l’option Comparer à une variable de contexte ou à un attribut personnalisé, vous pouvez construire des filtres de variables de contexte qui se comparent à des variables de contexte préalablement définies ou à des attributs personnalisés de l’utilisateur. Cela peut être utile pour effectuer des comparaisons dynamiques par utilisateur, comme celles déclenchées par l’API context, ou pour condenser une logique de comparaison complexe définie à travers des variables de contexte.

• example 1
• example 2

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 en fonction des résultats attendus.

Veillez à observer les scénarios courants qui créent des variables de contexte non valides. Lors de la prévisualisation de votre parcours d’utilisateur, vous pouvez visualiser les résultats des étapes de délai personnalisées à l’aide de variables de contexte, ainsi que toutes les comparaisons d’étapes d’audience, de décision ou de parcours d’action qui font correspondre les utilisateurs à n’importe quelle variable de contexte.

Si la variable de contexte est valide, vous pouvez y faire référence dans l’ensemble de votre Canvas. Cependant, si la variable de contexte n’a pas été créée correctement, les étapes ultérieures de votre canvas ne fonctionneront pas non plus correctement. Par exemple, si vous créez une étape Contexte pour attribuer une heure de rendez-vous aux utilisateurs, mais que vous fixez la valeur de l’heure de rendez-vous à une date passée, l’e-mail de rappel de votre étape Message ne sera jamais envoyé.

Conversion des chaînes de contenu connecté en JSON

Lors d’un appel au contenu connecté dans une étape de Context, le JSON renvoyé par l’appel sera évalué comme un type de données de type chaîne de caractères pour des raisons de cohérence et de prévention des erreurs. Si vous souhaitez convertir cette chaîne de caractères en JSON, convertissez-la en utilisant as_json_string. Par exemple :

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

Normalisation de la cohérence des fuseaux horaires

Avec l’ajout de Canvas Context, tous les horodatages de type datetime provenant des propriétés d’événements déclencheurs dans les Canvas basés sur l’action seront toujours normalisés en UTC. Auparavant, les horodatages des propriétés d’événement étaient normalisés en UTC, à quelques exceptions près. Désormais, l’expérience de modification des étapes du canvas et des messages sera plus cohérente.

Examinez cet exemple de la manière dont cette modification pourrait affecter un horodatage dans Canvas. Supposons que nous ayons un canevas basé sur des actions qui utilise une propriété d’événement dans la première étape du canevas avec l’étape de message suivante :

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

!Voyage en contexte avec un envoi de messages comme première étape.](/docs/fr/assets/img/context_timezone_example.png?1c9dbf77ef4fc87a4133f7470b7cbbb4){: style=”max-width:50%”}

L’étape aura également une charge utile d’événement comme :

1
2
3
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
}

Historiquement, le message serait le suivant : Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

Avec l’accès anticipé à Canvas Context, le message sera désormais le suivant : Your appointment is scheduled for 2025-08-05 4:15pm, we’ll see you then! Cela est dû au fait que l’horodatage est en UTC, c’est-à-dire 8 heures avant l’heure du Pacifique (le fuseau horaire spécifié dans la charge utile d’origine avec -08:00).

Utilisation de Liquid pour indiquer un horodatage dans votre fuseau horaire préféré

Considérez l’extrait de code liquide suivant :

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!

Cette logique aboutit à la sortie suivante : Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

Le fuseau horaire préféré peut également être envoyé dans la charge utile 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"
}

Voici un exemple d’extrait de code liquide :

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

Résolution des problèmes

Variables de contexte non valides

Une variable de contexte est considérée comme invalide lorsque

• L’appel à un contenu connecté intégré échoue.
• Au moment de l’exécution, l’expression Liquid renvoie 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 contextuelle est Number mais que l’expression Liquid renvoie une chaîne de caractères, elle n’est pas valide.

Dans ces conditions :

• L’utilisateur passe à l’étape suivante.
• L’analyse/analytique de l’étape du canvas considérera que cette information n’a pas été mise à jour.

Lors de la résolution des problèmes, surveillez les indicateurs de non-actualisation pour vérifier que votre variable contextuelle est correctement mise à jour. Si la variable de contexte n’est pas valide, vos utilisateurs peuvent continuer dans votre Canvas après l’étape du contexte, mais ne pourront pas se qualifier pour les étapes suivantes.

Reportez-vous à la section Types de données variables contextuelles pour obtenir des exemples de configuration pour chaque type de données.

Questions fréquemment posées

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

Si vous participez à l’étape du canvas en accès anticipé, les propriétés d’entrée de Canvas sont désormais incluses en tant que variables de contexte de Canvas. Cela signifie que vous pouvez envoyer les propriétés de l’entrée Canvas à l’aide de l’API Braze et y faire référence 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 faire référence les unes aux autres dans une étape du contexte singulier ?

Oui. Toutes les variables d’une étape contextuelle sont évaluées dans l’ordre, ce qui signifie que vous pourriez avoir les variables contextuelles suivantes configurées :

Cela s’applique également à plusieurs étapes de Contexte. Imaginez par exemple la séquence suivante :

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

Les variables contextuelles utilisent leur valeur la plus récente tout au long du canvas, chaque mise à jour affectant toutes les étapes suivantes qui font référence à cette variable.

La normalisation de la cohérence des fuseaux horaires du contexte Canvas a-t-elle un impact sur les Canvas déclenchés par l’API ?

Non, cette modification n’a d’incidence que sur les toiles déclenchées par une action. Les horodatages envoyés dans les canevas déclenchés par l’API seront de type chaîne de caractères, et non de type heure, de sorte que le fuseau horaire d’origine est toujours préservé.

Quel est le lien avec les exceptions relevées dans les propriétés d’entrée et les propriétés d’événement de Canvas ?

La participation à l’accès anticipé à Canvas Context supprime ces exceptions, que vous utilisiez ou non une étape de Canvas Context.