Étiquettes de personnalisation prises en charge

Cet article de référence présente une liste complète des étiquettes de personnalisation Liquid prises en charge.

Résumé des tags pris en charge

Pour plus de commodité, un résumé des tags de personnalisation pris en charge est fourni ci-dessous. Pour plus de détails sur chaque type de tag et les bonnes pratiques, poursuivez votre lecture.

Remarque

Les propriétés de déclencheur API doivent utiliser deux accolades par tag : {{api_trigger_properties.${your_api_trigger_property}}}. Les triples accolades (par exemple {{{...}}}) ne constituent pas une syntaxe de personnalisation Braze valide. Consultez Pourquoi mon Liquid déclenché par API échoue-t-il dans Braze ?.

Attributs pris en charge

Les attributs de Campaign, de carte et de Canvas ne sont pris en charge que dans leurs modèles de communication correspondants. Par exemple, dispatch_id est pris en charge dans Liquid pour les canaux de communication tels que l’e-mail, les notifications push, les SMS et WhatsApp, mais pas pour les messages in-app ni les bannières.

Consultez Attributs de Campaign et Canvas selon les sources pour plus de détails.

Différences entre les tags Canvas et Campaign

Le comportement des tags suivants diffère entre Canvas et Campaigns :

• Le comportement de dispatch_id diffère car Braze traite les étapes Canvas comme des événements déclenchés, même lorsqu’elles sont « planifiées » (à l’exception des étapes d’entrée, qui peuvent être planifiées). Pour plus d’informations, consultez Comportement du dispatch ID.
• L’utilisation du tag {{campaign.${name}}} avec Canvas affiche le nom du composant Canvas. Lorsque vous utilisez ce tag avec Campaigns, il affiche le nom de la campagne.

Noms de Campaign dans les URL

Les noms de Campaign et de variante de message peuvent contenir des caractères non sécurisés pour les URL, tels que %, des espaces ou &. Lorsque vous insérez {{campaign.${name}}} ou {{campaign.${message_name}}} dans un lien ou une chaîne de requête, comme un paramètre utm_campaign, appliquez le filtre url_encode afin que l’URL soit analysée correctement. Par exemple :

1
https://example.com/?utm_campaign={{ campaign.${name} | url_encode }}

Informations sur l’appareil le plus récemment utilisé

Vous pouvez utiliser les attributs suivants pour l’appareil le plus récent de l’utilisateur sur toutes les plateformes. Si un utilisateur n’a pas utilisé votre application (par exemple, si vous avez importé l’utilisateur via la REST API), alors toutes ces valeurs sont null.

Étant donné la grande variété d’opérateurs, de noms de modèles et de systèmes d’exploitation, nous vous conseillons de tester minutieusement tout code Liquid qui dépend conditionnellement de l’une de ces valeurs. Ces valeurs sont null si elles ne sont pas disponibles sur un appareil donné.

Informations sur l’application ciblée

Pour les messages in-app, vous pouvez utiliser les attributs d’application suivants dans Liquid. Les valeurs sont basées sur la clé API du SDK que vos applications utilisent pour demander l’envoi de messages.

Par exemple, ce code Liquid interrompt un message si les applications qui le demandent ne correspondent pas à l’une des deux clés API de la liste :

1
2
3
4
5
6
{% assign allowed_api_keys = 'sdk_api_key_1,sdk_api_key_2' | split: ',' %}
{% if allowed_api_keys contains {{app.${api_id}}} %}
User is in list of apps
{% else %}
{% abort_message("User not in list of apps") %}
{% endif %}

Informations sur l’appareil ciblé

Pour les notifications push, les messages in-app et les Banners, vous pouvez utiliser les attributs suivants de l’appareil qui reçoit le message dans vos modèles. Une notification push, un message in-app ou un Banner peut inclure les attributs de l’appareil sur lequel l’utilisateur lit le message. Ces attributs ne fonctionnent pas pour les Content Cards ni pour les e-mails. Pour les e-mails, les messages sont rendus avant l’envoi, de sorte que l’appareil sur lequel l’utilisateur ouvre l’e-mail est inconnu à ce moment-là.

Étant donné la grande variété d’opérateurs, de noms de modèles et de systèmes d’exploitation, nous vous conseillons de tester minutieusement toute logique qui dépend conditionnellement de l’une de ces valeurs. Ces valeurs sont null si elles ne sont pas disponibles sur un appareil donné.

De plus, pour les notifications push, il est possible que Braze ne puisse pas déterminer l’appareil associé à la notification push dans certaines circonstances, par exemple si le jeton push a été importé via l’API, ce qui entraîne des valeurs null pour ces messages.

Utiliser la logique conditionnelle au lieu d’une valeur par défaut

Dans certaines circonstances, vous pouvez choisir d’utiliser la logique conditionnelle au lieu de définir une valeur par défaut. La logique conditionnelle vous permet d’envoyer des messages qui diffèrent en fonction de la valeur d’un attribut personnalisé. De plus, vous pouvez utiliser la logique conditionnelle pour interrompre les messages destinés aux clients dont les valeurs d’attribut sont null ou vides.

Cas d’usage

Par exemple, imaginons que vous envoyez une notification de solde de récompenses à vos clients. Il n’existe pas de bonne façon de gérer les clients avec des soldes faibles ou null en utilisant des valeurs par défaut.

Dans ce cas, deux options peuvent mieux fonctionner que la définition d’une valeur par défaut :

1. Interrompre le message pour les clients avec des soldes faibles, null ou vides.

   1
   2
   3
   4
   5
   {% if {{custom_attribute.${balance}}} > 0 %}
   Your rewards balance is {{custom_attribute.${balance}}}
   {% else %}
   {% abort_message() %}
   {% endif %}
   

2. Envoyer un message complètement différent à ces clients, par exemple :

   1
   2
   3
   4
   5
   {% if ${first_name} != blank and ${first_name} != null %}
   Hello {{${first_name} | default: 'there'}}, thanks for downloading!
   {% else %}
   Thanks for downloading!
   {% endif %}
   

Dans ce cas d’usage, un utilisateur dont le prénom est vide ou null reçoit le message « Thanks for downloading ». Vous devriez inclure une valeur par défaut pour le prénom afin de vous assurer que votre client ne voit pas de Liquid en cas d’erreur.

Étiquettes de variables

Vous pouvez utiliser l’étiquette assign pour créer une variable dans le composeur de messages. Nous vous recommandons d’utiliser un nom unique pour votre variable. Si vous créez une variable avec un nom similaire aux étiquettes de personnalisation prises en charge (comme language), cela peut affecter votre logique de communication.

Après avoir créé une variable, vous pouvez la référencer dans votre logique de communication ou votre message. Cette étiquette est particulièrement utile lorsque vous souhaitez reformater du contenu renvoyé par notre fonctionnalité de contenu connecté. Vous pouvez en savoir plus dans la documentation de Shopify sur les étiquettes de variables.

Important

Les chaînes de caractères encadrées par des guillemets simples à l’intérieur d’une étiquette assign sont traitées comme des chaînes littérales. Les étiquettes de personnalisation Liquid à l’intérieur de guillemets simples ne sont pas interpolées. Par exemple :

1
2
{% assign name_intro = 'My name is {{${first_name}}}' %}
{{ name_intro }}

Cela affiche le texte littéral My name is {{${first_name}}} au lieu du prénom de l’utilisateur.

Pour inclure de la personnalisation, utilisez des variables ou concaténez des chaînes de caractères avec le filtre append. Pour le templating d’URL avec personnalisation, consultez les modèles de liens.

Conseil

Vous vous retrouvez à assigner les mêmes variables dans chaque message ? Au lieu de réécrire l’étiquette assign à chaque fois, vous pouvez enregistrer cette étiquette en tant que bloc de contenu et la placer en haut de votre message.

1. Créez un bloc de contenu.
2. Donnez un nom à votre bloc de contenu (sans espaces ni caractères spéciaux).
3. Sélectionnez Modifier en bas de la page.
4. Saisissez vos étiquettes assign.

Tant que le bloc de contenu se trouve en haut de votre message, chaque fois que la variable est insérée dans votre message en tant qu’objet, elle fait référence à l’attribut personnalisé que vous avez choisi.

Cas d’usage

Imaginons que vous permettez à vos clients d’échanger leurs points de récompense contre des prix après avoir accumulé 100 points de récompense. Vous souhaitez donc envoyer un message uniquement aux clients dont le solde de points serait supérieur ou égal à 100 s’ils effectuaient cet achat supplémentaire :

1
2
3
4
5
6
{% assign new_points_balance = {{custom_attribute.${current_rewards_balance} | plus: 50}} %}
{% if new_points_balance >= 100 %}
Make a purchase to bring your rewards points to {{new_points_balance}} and cash in today!
{% else %}
{% abort_message('not enough points') %}
{% endif %}

Étiquettes d’itération

Les étiquettes d’itération peuvent être utilisées pour exécuter un bloc de code de manière répétée. Le cas d’usage ci-dessous utilise l’étiquette for.

Cas d’usage

Imaginons que vous organisez une promotion sur les baskets Nike et que vous souhaitez envoyer un message aux clients qui ont exprimé un intérêt pour Nike. Vous disposez d’un tableau de marques de produits consultées sur le profil de chaque client. Ce tableau peut contenir jusqu’à 25 marques de produits, mais vous souhaitez uniquement envoyer un message aux clients qui ont consulté un produit Nike parmi leurs 5 consultations de produits les plus récentes.

1
2
3
4
5
6
7
8
9
10
{% for items in {{custom_attribute.${Brands Viewed}}} limit:5 %}
{% if {{items}} contains 'Converse' %}
{% assign converse_viewer = true %}
{% endif %}
{% endfor %}
{% if converse_viewer == true %}
Sale on Converse!
{% else %}
{% abort_message() %}
{% endif %}

Dans ce cas d’usage, nous vérifions les cinq premiers éléments du tableau des marques de baskets consultées. Si l’un de ces éléments est Converse, nous créons la variable converse_viewer et la définissons sur true.

Ensuite, nous envoyons le message de promotion lorsque converse_viewer est true. Sinon, nous interrompons le message.

Il s’agit d’un exemple simple de la façon dont les étiquettes d’itération peuvent être utilisées dans le composeur de messages de Braze. Vous trouverez plus d’informations dans la documentation de Shopify sur les étiquettes d’itération.

Étiquettes de syntaxe

Les étiquettes de syntaxe peuvent être utilisées pour contrôler le rendu de Liquid. Vous pouvez utiliser l’étiquette echo pour retourner une expression. Cela revient à encadrer une expression avec des accolades, sauf que vous pouvez utiliser cette étiquette à l’intérieur d’étiquettes Liquid. Vous pouvez également utiliser l’étiquette liquid pour avoir un bloc de Liquid sans aucun délimiteur sur chaque étiquette. Chaque étiquette doit être sur sa propre ligne lorsque vous utilisez l’étiquette liquid. Consultez la documentation de Shopify sur les étiquettes de syntaxe pour plus d’informations et d’exemples.

Avec le contrôle des espaces, vous pouvez supprimer les espaces autour de vos étiquettes, ce qui vous aide à mieux contrôler l’apparence de la sortie Liquid.

Codes de statut HTTP

Vous pouvez utiliser le statut HTTP d’un appel de contenu connecté en l’enregistrant d’abord en tant que variable locale, puis en utilisant la clé __http_status_code__. Par exemple :

1
2
3
4
{% connected_content https://example.com/api/endpoint :save connected %}
{% if connected.__http_status_code__ != 200 %}
{% abort_message('Connected Content returned a non-200 status code') %}
{% endif %}

Remarque

Cette clé n’est ajoutée automatiquement à l’objet de contenu connecté que si l’endpoint renvoie un objet JSON. Si l’endpoint renvoie un tableau ou un autre type, cette clé ne peut pas être définie automatiquement dans la réponse.

Envoyer des messages en fonction de la langue, de la locale la plus récente et du fuseau horaire

Dans certaines situations, vous pouvez souhaiter envoyer des messages spécifiques à des locales particulières. Par exemple, le portugais brésilien est généralement différent du portugais européen.

Cas d’usage : localiser en fonction de la locale la plus récente

Voici un cas d’usage montrant comment utiliser la locale la plus récente pour affiner la localisation d’un message internationalisé.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{% if ${language} == 'en' %}
Message in English
{% elsif  ${language} == 'fr' %}
Message in French
{% elsif  ${language} == 'ja' %}
Message in Japanese
{% elsif  ${language} == 'ko' %}
Message in Korean
{% elsif  ${language} == 'ru' %}
Message in Russian
{% elsif ${most_recent_locale} == 'pt_BR' %}
Message in Brazilian Portuguese
{% elsif ${most_recent_locale} == 'pt_PT' %}
Message in European Portuguese
{% elsif  ${language} == 'pt' %}
Message in default Portuguese
{% else %}
Message in default language
{% endif %}

Dans ce cas d’usage, les clients dont la locale la plus récente est pt_BR reçoivent un message en portugais brésilien, et ceux dont la locale la plus récente est pt_PT reçoivent un message en portugais européen. Les clients qui ne remplissent pas les deux premières conditions mais dont la langue est définie sur le portugais reçoivent un message dans le type de portugais par défaut de votre choix.

Cas d’usage : cibler les utilisateurs par fuseau horaire

Vous pouvez également cibler les utilisateurs en fonction de leur fuseau horaire. Par exemple, envoyez un message s’ils se trouvent dans le fuseau EST et un autre s’ils sont dans le fuseau PST. Pour ce faire, enregistrez l’heure actuelle en UTC et comparez une instruction if/else avec l’heure actuelle de l’utilisateur afin d’envoyer le bon message pour le bon fuseau horaire. Vous devez configurer la Campaign pour qu’elle s’envoie dans le fuseau horaire local de l’utilisateur, afin qu’il la reçoive au bon moment.

Consultez le cas d’usage suivant pour savoir comment rédiger un message distribué entre 14 h et 15 h avec un contenu spécifique pour chaque fuseau horaire.

1
2
3
4
5
6
7
8
{% assign hour_in_utc = 'now' | date: '%H' | plus:0 %}
{% if hour_in_utc >= 19 && hour_in_utc < 20 %}
It is between 2:00:00 pm and 2:59:59 pm ET!
{% elsif hour_in_utc >= 22 && hour_in_utc < 23 %}
It is between 2:00:00 pm and 2:59:59 pm PT!
{% else %}
{% abort_message %}
{% endif %}

Envoyer des messages avec un nombre aléatoire

La balise {% random %} renvoie un nombre aléatoire. Vous pouvez l’utiliser pour une logique de type A/B, un échantillonnage ou pour varier le contenu des messages.

Cas d’usage : envoyer des variantes aléatoires aux utilisateurs

1
2
3
4
5
6
7
{% capture roll_str %}{% random %}{% endcapture %}
{% assign roll = roll_str | plus: 0 %}
{% if roll < 0.5 %}
Show variant A
{% else %}
Show variant B
{% endif %}

Étiquette de panier d’achat eCommerce

L’étiquette shopping_cart accède au contenu du panier d’un utilisateur dans les cas d’usage eCommerce Canvas de panier abandonné et de paiement abandonné. Remplacez CART_ID par la valeur réelle de l’ID du panier, comme {{context.${cart_id}}}.

1
{% shopping_cart CART_ID :abort_if_not_abandoned false %}

Le paramètre abort_if_not_abandoned dans cet exemple s’applique uniquement au cas d’usage de paiement abandonné lorsqu’il est utilisé avec l’événement ecommerce.checkout_started. Il ne s’applique pas aux cas d’usage de panier abandonné. Pour plus de détails, consultez abort_if_not_abandoned.