Utilisation de la syntaxe Liquid

Liquid est un langage de template pris en charge par OneSignal pour personnaliser les messages sur tous les canaux, y compris l’e-mail, le push, les SMS, l’in-app et les Live Activities. Il utilise des balises, des filtres et des conditionnels pour personnaliser dynamiquement le contenu des messages. Pour en savoir plus sur la syntaxe Liquid, consultez la documentation Liquid officielle.

Syntaxe de base

Liquid utilise deux structures de syntaxe principales :

Balises de sortie : {{ ... }} — Affiche les données d’une variable ou d’un objet.
Balises logiques : {% ... %} — Exécute des instructions conditionnelles ou des boucles.

Conditionnels

Opérateurs

==, !=, >, <, >=, <=
and, or
contains (chaîne ou tableau)

liquid

{% if true or false and false %}
  This is true.
{% endif %}

`if`, `elsif`, `else`

liquid

{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}

`unless`

liquid

{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}

Filtres

Appliquez des filtres en utilisant {{ variable | filter }} pour ajuster la façon dont les données sont affichées.

`default`

Attribue une valeur par défaut si la propriété est vide ou n’existe pas.

liquid

Hello {{ first_name | default: "there" }}.

`date`

Le filtre date convertit un timestamp en un autre format de date. Le format de cette syntaxe est le même que strftime. L’entrée utilise le même format que la méthode Time.parse de Ruby. Définissez les dates comme un timestamp unix en secondes avec des tags. Cela permet d’utiliser à la fois la personnalisation avec la syntaxe Liquid et la segmentation avec les Opérateurs de temps. Par exemple, un tag pourrait ressembler à : bill_due : 1687968776

liquid

{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}

Result

Wed, Jun 28, 23

liquid

{{ bill_due | date: "%Y" }}

Result

Le formatage de date fonctionne sur les chaînes si elles contiennent des dates bien formatées.

liquid

{{ "March 14, 2016" | date: "%b %d, %y" }}

Result

Mar 14, 16

Pour obtenir l’heure actuelle, passez le mot spécial now (ou today) avec le filtre date.

liquid

This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

Result

This message was sent at 2022-11-02 14:39.

L’heure actuelle sera affichée dans le message en fonction du moment où le message est envoyé au destinataire. Si vous testez le message, vous verrez l’heure actuelle comme étant celle de l’envoi du message de test.

`capitalize`

Ce filtre met en majuscule le premier caractère d’une chaîne et convertit les caractères restants en minuscules.

liquid

{{ "my GREAT title" | capitalize }}

Result

My great title

`round`

Ce filtre arrondit un nombre à l’entier le plus proche ou, si un nombre est passé en argument, à ce nombre de décimales.

liquid

{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}

Result

1
3
183.36

`pluralize`

Ce filtre retourne la forme singulière ou plurielle d’une chaîne en fonction d’un nombre donné. Le nombre doit être un nombre entier et peut être fourni sous forme de chaîne. Les formes singulière et plurielle d’une chaîne doivent être fournies.

liquid

{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}

Result

singular
plural
1 person
2 people
2 people

Itération

Boucles `for`

Exécute à plusieurs reprises un bloc de code. Pour une liste complète des attributs disponibles dans une boucle for, consultez la documentation de la boucle for Liquid.

liquid

{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    Sorry, we're sold out of all products.
  {% endfor %}

Request Body

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "custom_data": {
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}

Result

- Sweater
- Hat
- Shirt

(Si message.custom_data.products est vide)
Désolé, nous n'avons plus aucun produit en stock.

Bien que puissante et flexible, l’utilisation de boucles for dans la syntaxe Liquid peut entraîner de mauvaises performances de livraison de notifications dans certains cas rares. Soyez attentif à votre utilisation des boucles for. Notez également que nous empêchons l’utilisation de boucles for dans quelques champs du canal Push : contents, headings, subtitle, apns_alert et url

`limit` & `offset`

Limite la boucle au nombre d’itérations spécifié. Par exemple, si vous voulez uniquement afficher 4 produits dans un message, vous pouvez utiliser Limits et Offsets pour spécifier le nombre de produits affichés.

Data

great_numbers = [1,2,3,4,5,6]

liquid

{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}

Result

1 2

Pour commencer la boucle à l’index spécifié, ajoutez une valeur offset :

Data

great_numbers = [1,2,3,4,5,6]

liquid

{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}

Result

1 2 3
4 5 6

`where`

Crée un tableau incluant uniquement les objets avec une valeur de propriété donnée, ou toute valeur vraie par défaut. Dans cet exemple, supposons que vous ayez une liste de produits et que vous souhaitiez afficher vos produits de cuisine séparément. En utilisant where, vous pouvez créer un tableau contenant uniquement les produits ayant un type de kitchen.

Data

products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]

liquid

All products:
{% for product in products %}
- {{ product.name }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}

Result

All products:
  - Vacuum
  - Spatula
  - Television
  - Garlic press

Kitchen products:
- Spatula
- Garlic press

Manipulation de chaînes

Appliquez des filtres de chaîne pour ajuster la façon dont les valeurs de balises ou les chaînes en ligne sont affichées dans les messages.

Commande	Description	Exemple	Sortie d’exemple
`replace`	Remplace une sous-chaîne par une autre chaîne.	`{{ 'hello world' \| replace: 'world', 'there' }}`	hello there
`capitalize`	Met en majuscule la première lettre d’une chaîne.	`{{ 'hello' \| capitalize }}`	Hello
`upcase`	Convertit une chaîne en majuscules.	`{{ 'hello' \| upcase }}`	HELLO
`downcase`	Convertit une chaîne en minuscules.	`{{ 'HELLO' \| downcase }}`	hello
`strip`	Supprime les espaces blancs de début et de fin d’une chaîne.	`{{ ' hello ' \| strip }}`	hello
`strip_html`	Supprime toutes les balises HTML d’une chaîne.	`{{ '<p>hello</p>' \| strip_html }}`	hello
`truncate`	Raccourcit une chaîne à une longueur spécifiée, en ajoutant des points de suspension (…) si nécessaire.	`{{ 'This is a long sentence' \| truncate: 10 }}`	This is a…
`truncatewords`	Tronque une chaîne après un certain nombre de mots.	`{{ 'This is a long sentence' \| truncatewords: 2 }}`	This is…
`replace_first`	Remplace la première occurrence d’une sous-chaîne.	`{{ 'hello world' \| replace_first: 'world', 'there' }}`	hello there
`prepend`	Ajoute une chaîne au début d’une autre chaîne.	`{{ 'world' \| prepend: 'hello ' }}`	hello world
`append`	Ajoute une chaîne à la fin d’une autre chaîne.	`{{ 'hello' \| append: ' world' }}`	hello world
`lstrip`	Supprime les espaces blancs de début d’une chaîne.	`{{ ' hello' \| lstrip }}`	hello
`rstrip`	Supprime les espaces blancs de fin d’une chaîne.	`{{ 'hello ' \| rstrip }}`	hello

FAQ

Pourquoi la substitution ne fonctionne-t-elle pas ?

Les messages in-app ne prennent pas en charge la substitution de propriétés.
La substitution de tags ne fonctionne pas lors de l’utilisation de « Send Test Message ».
Les clés de tags doivent être alphanumériques, ou utiliser _ et - (pas de points ni d’espaces).
La substitution n’apparaît pas en mode aperçu — envoyez un vrai message pour tester.

Quand dois-je utiliser `default` plutôt que `if/else` ?

Utilisez le filtre default lorsque seule la valeur de la variable nécessite un fallback et que le texte environnant reste le même.

liquid

Hello {{ name | default: "there" }}!

Result (name = "Jon")

Hello Jon!

Result (name est vide)

Hello there!

Utilisez la logique conditionnelle if/else lorsque le texte environnant, la ponctuation ou la structure de la phrase doit également changer selon que la variable existe ou non.

liquid

{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}

Result (name = "Jon")

Jon, shop your favorites!

Result (name est vide)

Shop your favorites!

N’utilisez pas default lorsque la structure de la phrase change. Par exemple, {{ name | default: "Shop your favorites" }}, shop your favorites rendrait « Shop your favorites, shop your favorites » lorsque le nom est vide. Si le fallback change plus que juste la variable, utilisez if/else.

Comment contrôler les espaces blancs et les sauts de ligne ?

Utilisez des tirets : {{- ... -}}, {%- ... -%} pour supprimer les espaces blancs environnants. Consultez Contrôle des espaces blancs pour plus de détails.

Comment gérer le contenu généré par l’utilisateur ?

Enveloppez le texte généré par l’utilisateur dans {% raw %} et {% endraw %} pour empêcher l’analyse Liquid. Consultez syntaxe “raw”.

{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}

Pages associées

Personnalisation des messages

Vue d’ensemble de toutes les options de personnalisation, y compris Liquid, Data Feeds et les événements personnalisés.

Data Feeds

Récupérez des données en temps réel depuis vos API dans les messages au moment de l’envoi.

Balises

Stockez des paires clé-valeur sur les utilisateurs pour la segmentation et la personnalisation Liquid.

Modèles

Créez des modèles de messages réutilisables avec la personnalisation Liquid intégrée.

Premiers pas et paramètres

Canaux de messagerie

Journeys

Audience et événements personnalisés

Analyses et intégrations

Confidentialité et sécurité

Utilisation de la syntaxe Liquid

Syntaxe de base

Conditionnels

Opérateurs

`if`, `elsif`, `else`

`unless`

Filtres

`default`

`date`

`capitalize`

`round`

`pluralize`

Itération

Boucles `for`

`limit` & `offset`

`where`

Manipulation de chaînes

FAQ

Pourquoi la substitution ne fonctionne-t-elle pas ?

Quand dois-je utiliser `default` plutôt que `if/else` ?

Comment contrôler les espaces blancs et les sauts de ligne ?

Comment gérer le contenu généré par l’utilisateur ?

Pages associées

Personnalisation des messages

Data Feeds

Balises

Modèles

​Syntaxe de base

​Conditionnels

​Opérateurs

​if, elsif, else

​unless

​Filtres

​default

​date

​capitalize

​round

​pluralize

​Itération

​Boucles for

​limit & offset

​where

​Manipulation de chaînes

​FAQ

​Pourquoi la substitution ne fonctionne-t-elle pas ?

​Quand dois-je utiliser default plutôt que if/else ?

​Comment contrôler les espaces blancs et les sauts de ligne ?

​Comment gérer le contenu généré par l’utilisateur ?

​Pages associées

Personnalisation des messages

Data Feeds

Balises

Modèles

Syntaxe de base

Conditionnels

Opérateurs

`if`, `elsif`, `else`

`unless`

Filtres

`default`

`date`

`capitalize`

`round`

`pluralize`

Itération

Boucles `for`

`limit` & `offset`

`where`

Manipulation de chaînes

FAQ

Pourquoi la substitution ne fonctionne-t-elle pas ?

Quand dois-je utiliser `default` plutôt que `if/else` ?

Comment contrôler les espaces blancs et les sauts de ligne ?

Comment gérer le contenu généré par l’utilisateur ?

Pages associées