Usando sintaxe Liquid

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:

Output Tags: {{ ... }} — Exibem dados de uma variável ou objeto.
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

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.

Command	Description	Example	Example Output
`replace`	Substitui uma substring por outra string.	`{{ 'hello world' \| replace: 'world', 'there' }}`	hello there
`capitalize`	Torna a primeira letra de uma string maiúscula.	`{{ 'hello' \| capitalize }}`	Hello
`upcase`	Converte uma string para maiúsculas.	`{{ 'hello' \| upcase }}`	HELLO
`downcase`	Converte uma string para minúsculas.	`{{ 'HELLO' \| downcase }}`	hello
`strip`	Remove espaços em branco à esquerda e à direita de uma string.	`{{ ' hello ' \| strip }}`	hello
`strip_html`	Remove todas as tags HTML de uma string.	`{{ '<p>hello</p>' \| strip_html }}`	hello
`truncate`	Encurta uma string para um comprimento especificado, adicionando reticências (…) se necessário.	`{{ 'This is a long sentence' \| truncate: 10 }}`	This is a…
`truncatewords`	Trunca uma string após um certo número de palavras.	`{{ 'This is a long sentence' \| truncatewords: 2 }}`	This is…
`replace_first`	Substitui a primeira ocorrência de uma substring.	`{{ 'hello world' \| replace_first: 'world', 'there' }}`	hello there
`prepend`	Adiciona uma string ao início de outra string.	`{{ 'world' \| prepend: 'hello ' }}`	hello world
`append`	Adiciona uma string ao final de outra string.	`{{ 'hello' \| append: ' world' }}`	hello world
`lstrip`	Remove espaços em branco à esquerda de uma string.	`{{ ' hello' \| lstrip }}`	hello
`rstrip`	Remove 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.

Templates

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

Primeiros passos & configurações

Canais de mensagem

Jornadas

Público & eventos personalizados

Análises & Integrações

Privacidade & Segurança

Usando sintaxe Liquid

Sintaxe básica

Condicionais

Operadores

`if`, `elsif`, `else`

`unless`

Filtros

`default`

`date`

`capitalize`

`round`

`pluralize`

Iteração

Loops `for`

`limit` & `offset`

`where`

Manipulação de String

FAQ

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

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

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

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

Páginas relacionadas

Personalização de mensagens

Data Feeds

Tags

Templates

​Sintaxe básica

​Condicionais

​Operadores

​if, elsif, else

​unless

​Filtros

​default

​date

​capitalize

​round

​pluralize

​Iteração

​Loops for

​limit & offset

​where

​Manipulação de String

​FAQ

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

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

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

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

​Páginas relacionadas

Personalização de mensagens

Data Feeds

Tags

Templates

Sintaxe básica

Condicionais

Operadores

`if`, `elsif`, `else`

`unless`

Filtros

`default`

`date`

`capitalize`

`round`

`pluralize`

Iteração

Loops `for`

`limit` & `offset`

`where`

Manipulação de String

FAQ

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

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

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

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

Páginas relacionadas