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 remise différent chaque fois qu’un utilisateur entre dans le Canvas.

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 que dans le cadre de ce parcours Canvas et ne persistent ni 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 de manière permanente le profil de l’utilisateur et n’apparaissent pas dans d’autres Canvas. Elles sont donc idéales pour les informations temporaires qui ne concernent qu’une campagne ou un flux de travail spécifique.

Dans une étape Contexte, vous pouvez définir ou mettre à jour jusqu’à 10 variables de contexte. Ces variables peuvent servir à personnaliser les délais, segmenter dynamiquement les utilisateurs et enrichir l’envoi de messages dans l’ensemble du Canvas. Par exemple, vous pourriez 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 du Canvas : Les données provenant de l’événement ou du déclencheur API peuvent automatiquement remplir les variables de contexte.
• Dans une étape Contexte : Définissez ou mettez à jour manuellement les 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 le menu déroulant de l’éditeur d’étape. Pour plus de détails, consultez l’article de référence sur les 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 fonctionnant 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 à destination de New York, tout en envoyant des informations différentes concernant son vol de 8 h à destination de Los Angeles le lendemain, de sorte que chaque message reste pertinent par rapport à la réservation concernée.

Traitement et regroupement des utilisateurs

Les étapes Contexte traitent les utilisateurs par lots afin d’optimiser les performances. Lorsque les utilisateurs arrivent à une étape 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 de manière séquentielle.

Concrètement :

Exemple : Si 3 500 utilisateurs arrivent à une étape Contexte avec du contenu connecté qui prend 650 ms par utilisateur :

• Braze crée quatre 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, 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 passent à 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, en fonction de la taille du lot et des temps de réponse du contenu connecté.

Sans contenu connecté, les étapes Contexte s’exécutent 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 Contexte.
• Chaque variable doit avoir un nom unique (lettres, chiffres et underscores uniquement, jusqu’à 100 caractères).
• La taille totale de toutes les variables d’une étape ne doit 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 plus de détails et une utilisation avancée, consultez l’article de référence sur les variables de contexte.

Créer une étape Contexte

É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

Pour définir une variable de contexte :

1. Donnez un nom à votre variable de contexte.
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 Prévisualiser 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 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 des instructions détaillées, consultez l’article de référence sur les variables de contexte.

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 la configuration des filtres, la logique de comparaison et des exemples avancés, consultez l’article de référence sur les variables de contexte.

Prévisualiser les parcours utilisateur

Nous vous recommandons de tester et de prévisualiser vos parcours utilisateur afin de vous assurer que vos messages sont envoyés à la bonne audience et que les variables de contexte produisent les résultats attendus.

Veillez à prendre en compte tous les scénarios courants susceptibles de générer des variables de contexte non valides. Lorsque vous prévisualisez votre parcours utilisateur, vous pouvez visualiser les résultats des étapes de délai personnalisées utilisant des variables de contexte, ainsi que toutes les comparaisons d’audience ou d’arbre décisionnel qui associent les utilisateurs à des variables de contexte.

Si la variable de contexte est valide, vous pouvez y faire référence 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 un rendez-vous aux utilisateurs et que vous définissez la valeur du rendez-vous sur une date passée, l’e-mail de rappel de votre étape Message ne sera pas envoyé.

Convertir les chaînes de contenu connecté en JSON

Lorsqu’un appel de contenu connecté est effectué dans une étape 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 :

• 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 attendu ou qui est vide (null).

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 est non valide.

Dans ce cas :

• L’utilisateur passe à l’étape suivante.
• L’analytique de l’étape du Canvas comptabilise cela 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 est correctement mise à jour. Si la variable de contexte est non valide, vos utilisateurs peuvent continuer dans votre Canvas après l’étape Contexte, mais risquent de ne pas se qualifier pour les étapes suivantes.

Consultez la section Types de données pour des exemples de configuration pour chaque type de données.

Retards d’envoi avec le contenu connecté

Tous les utilisateurs d’un lot sont traités avant que quiconque ne puisse avancer. Une fois le traitement du lot terminé, les utilisateurs traités avec succès passent à l’étape suivante, tandis que ceux ayant échoué font l’objet d’une nouvelle tentative séparée. Les utilisateurs traités avec succès n’attendent pas que les nouvelles tentatives aboutissent avant d’avancer.

Comportement de réessai : Les étapes Contexte (et toutes les étapes du Canvas) utilisent des mécanismes de nouvelle tentative spécifiques au Canvas, et non le comportement de nouvelle tentative standard du contenu connecté. Si un appel de contenu connecté échoue, Braze réessaie l’étape environ 13 fois avec des délais exponentiels. Si toutes les tentatives échouent, l’utilisateur quitte le Canvas.

Temps de traitement : Le temps nécessaire pour traiter tous les utilisateurs via une étape Contexte dépend de :

• Le nombre d’utilisateurs entrant dans l’étape
• L’utilisation ou non du 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é est soumis à des limites de débit, notez que les étapes Contexte traitent les utilisateurs de manière séquentielle au sein de chaque lot, ce qui contribue naturellement au respect de ces limites. Cependant, plusieurs lots sont traités en parallèle : assurez-vous donc que votre endpoint peut gérer les requêtes simultanées provenant de plusieurs lots.

Normalisation des fuseaux horaires

Avec la disponibilité générale de Canvas Context, toutes les propriétés d’événement d’horodatage par défaut dans les Canvas basés sur les actions sont désormais en UTC. Ce changement s’inscrit dans une initiative plus large visant à garantir une expérience plus prévisible et cohérente lors de la modification des étapes du Canvas et des messages. Notez que cette modification affecte tous les Canvas basés sur des actions, que le Canvas en question utilise ou non une étape Contexte.

Foire aux questions

Quels changements ont été apportés depuis que Canvas Context est devenu accessible à tous ?

Maintenant que Canvas Context est disponible pour tous, voici ce qui s’applique :

• Tous les horodatages de type datetime provenant des propriétés d’événement déclencheur dans les Canvas basés sur des actions sont exprimés en UTC.
• Cette modification affecte tous les Canvas basés sur des actions, que le Canvas en question utilise ou non une étape Contexte.

Quelle est la raison de ce changement ?

Ce changement s’inscrit dans une initiative plus large visant à offrir une expérience plus prévisible et cohérente lors de la modification des étapes du Canvas et des messages.

Les Canvas déclenchés par API ou planifiés sont-ils affectés par ce changement ?

Non.

Ce changement affecte-t-il les propriétés d’entrée du Canvas ?

Oui, cela a une incidence sur 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 illustrant comment procéder :

Quel est un exemple concret de la façon dont le nouveau comportement de l’horodatage pourrait affecter mes messages ?

Supposons que nous ayons un Canvas basé sur les actions contenant le texte 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 génère le message suivant :

1
Your appointment is scheduled for 2025-08-05 4:15pm, we’ll see you then!

Étant donné qu’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 suit :

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 génère le message suivant :

1
Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

Étant donné que le fuseau horaire America/Los_Angeles est spécifié à l’aide de Liquid, l’horodatage est ici en heure 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 du Canvas ?

Les propriétés d’entrée du Canvas sont incluses en tant que variables de contexte Canvas. Cela signifie que vous pouvez envoyer les propriétés d’entrée du Canvas via l’API Braze et y faire référence dans d’autres étapes, de la même manière qu’une variable de contexte avec un extrait de code Liquid.

Les variables peuvent-elles faire référence les unes aux autres dans une même étape Contexte ?

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

Cela s’applique également à plusieurs étapes 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’utilisateur.
3. Plus tard, une étape Contexte met à jour la variable de contexte en changeant la valeur de JobInfo en job_description.
4. Toutes les étapes suivantes qui font référence à 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 font référence à cette variable.