Pular para o conteúdo principal
Liquid é uma linguagem de templating suportada pelo OneSignal para personalizar mensagens através de canais incluindo email, push, SMS, in-app e Live Activities. Ela usa tags, filtros e condicionais para personalizar dinamicamente o conteúdo da mensagem. Para aprender mais sobre sintaxe Liquid, veja a documentação oficial do Liquid.

​
Sintaxe básica

Liquid usa duas estruturas de sintaxe principais:
  1. Output Tags: {{ ... }} — Exibem dados de uma variável ou objeto.
  2. Logic Tags: {% ... %} — Executam instruções condicionais ou loops.

​
Condicionais

​
Operadores

  • ==, !=, >, <, >=, <=
  • and, or
  • contains (string ou array)
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 %}

​
Filtros

Aplique filtros usando {{ variable | filter }} para ajustar como os dados são exibidos.

​
default

Atribua um valor padrão se a propriedade estiver vazia ou não existir.
liquid
Hello {{ first_name | default: "there" }}.

​
date

O filtro date converte um timestamp em outro formato de data. O formato para esta sintaxe é o mesmo que strftime. A entrada usa o mesmo formato que Ruby’s Time.parse. Defina datas como um timestamp unix em segundos com tags. Isso permite o uso tanto de personalização de sintaxe Liquid quanto de segmentação com Time Operators. Por exemplo, uma tag pode parecer com: 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
2023
Formatação de data funciona em strings se elas contiverem datas bem formatadas.
liquid
{{ "March 14, 2016" | date: "%b %d, %y" }}
Result
Mar 14, 16
Para obter a hora atual, passe a palavra especial now (ou today) junto com o filtro 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.
A hora atual será renderizada na mensagem com base em quando a mensagem é enviada ao destinatário. Se você estiver testando a mensagem, você verá a hora atual como quando a mensagem de teste foi enviada.

​
capitalize

Este filtro torna a primeira letra de uma string maiúscula e converte os caracteres restantes em minúsculas.
liquid
{{ "my GREAT title" | capitalize }}
Result
My great title

​
round

Este filtro arredonda um número para o inteiro mais próximo, ou, se um número for passado como argumento, para aquele número de casas decimais.
liquid
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
Result
1
3
183.36

​
pluralize

Este filtro retorna a forma singular ou plural de uma string com base em um número fornecido. O número deve ser um número inteiro e pode ser fornecido como uma string. As formas singular e plural de uma string devem ser fornecidas.
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

​
Iteração

​
Loops for

Executa repetidamente um bloco de código. Para uma lista completa de atributos disponíveis dentro de um loop for, consulte a documentação do loop for do 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

(Se message.custom_data.products estiver vazio)
Desculpe, estamos sem estoque de todos os produtos.
Embora poderoso e flexível, o uso de loops for em sintaxe Liquid pode levar a baixo desempenho de entrega de notificações em certos casos raros. Seja consciente do seu uso de loops for. Também note que prevenimos o uso de loops for em alguns campos do canal Push: contents, headings, subtitle, apns_alert e url

​
limit & offset

Limita o loop ao número especificado de iterações. Por exemplo, se você deseja apenas mostrar 4 produtos em uma mensagem, você pode usar Limits e Offsets para especificar o número de produtos mostrados.
Data
great_numbers = [1,2,3,4,5,6]
liquid
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
Result
1 2
Para iniciar o loop no índice especificado, adicione um valor de 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

Cria um array incluindo apenas os objetos com um valor de propriedade fornecido, ou qualquer valor verdadeiro por padrão. Neste exemplo, assuma que você tem uma lista de produtos e deseja mostrar seus produtos de cozinha separadamente. Usando where, você pode criar um array contendo apenas os produtos que têm um 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

​
Manipulação de String

Aplique filtros de string para ajustar como valores de tags ou strings inline são exibidos nas mensagens.
CommandDescriptionExampleExample Output
replaceSubstitui uma substring por outra string.{{ 'hello world' | replace: 'world', 'there' }}hello there
capitalizeTorna a primeira letra de uma string maiúscula.{{ 'hello' | capitalize }}Hello
upcaseConverte uma string para maiúsculas.{{ 'hello' | upcase }}HELLO
downcaseConverte uma string para minúsculas.{{ 'HELLO' | downcase }}hello
stripRemove espaços em branco à esquerda e à direita de uma string.{{ ' hello ' | strip }}hello
strip_htmlRemove todas as tags HTML de uma string.{{ '<p>hello</p>' | strip_html }}hello
truncateEncurta uma string para um comprimento especificado, adicionando reticências (…) se necessário.{{ 'This is a long sentence' | truncate: 10 }}This is a…
truncatewordsTrunca uma string após um certo número de palavras.{{ 'This is a long sentence' | truncatewords: 2 }}This is…
replace_firstSubstitui a primeira ocorrência de uma substring.{{ 'hello world' | replace_first: 'world', 'there' }}hello there
prependAdiciona uma string ao início de outra string.{{ 'world' | prepend: 'hello ' }}hello world
appendAdiciona uma string ao final de outra string.{{ 'hello' | append: ' world' }}hello world
lstripRemove espaços em branco à esquerda de uma string.{{ ' hello' | lstrip }}hello
rstripRemove espaços em branco à direita de uma string.{{ 'hello ' | rstrip }}hello

​
FAQ

​
Por que a substituição não está funcionando?

  • Mensagens in-app não suportam substituição de propriedade.
  • Substituição de tag não funciona ao usar “Send Test Message”.
  • Chaves de tag devem ser alfanuméricas, ou usar _ e - (sem pontos ou espaços).
  • Substituição não aparece em modo preview — envie uma mensagem real para testar.

​
Quando devo usar default em vez de if/else?

Use o filtro default quando apenas o valor da variável precisa de um fallback e o texto ao redor permanece o mesmo.
liquid
Hello {{ name | default: "there" }}!
Result (name = "Jon")
Hello Jon!
Result (name está vazio)
Hello there!
Use a lógica condicional if/else quando o texto ao redor, a pontuação ou a estrutura da frase também precisar mudar com base na existência da variável.
liquid
{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}
Result (name = "Jon")
Jon, shop your favorites!
Result (name está vazio)
Shop your favorites!
Não use default quando a estrutura da frase muda. Por exemplo, {{ name | default: "Shop your favorites" }}, shop your favorites renderizaria como “Shop your favorites, shop your favorites” quando o nome estiver vazio. Se o fallback muda mais do que apenas a variável, use if/else.

​
Como controlar espaços em branco e quebras de linha?

Use hífens: {{- ... -}}, {%- ... -%} para remover espaços em branco ao redor. Veja Controle de espaços em branco para mais detalhes.

​
Como lidar com conteúdo gerado por usuários?

Envolva texto gerado por usuários em {% raw %} e {% endraw %} para prevenir análise Liquid. Veja sintaxe “raw”. 
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}

​
Páginas relacionadas

Personalização de mensagens

Visão geral de todas as opções de personalização, incluindo Liquid, Data Feeds e eventos personalizados.

Data Feeds

Puxe dados em tempo real de suas APIs para mensagens no momento do envio.

Tags

Armazene pares chave-valor em usuários para segmentação e personalização Liquid.

Templates

Crie templates de mensagens reutilizáveis com personalização Liquid integrada.