> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usando sintaxe Liquid

> Personalize conteúdo de email, push, SMS, in-app e Live Activity com tags, filtros, condicionais e loops Liquid — alimentado por fontes de dados do OneSignal como tags, propriedades, dados personalizados e Data Feeds.

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](https://shopify.github.io/liquid/basics/introduction/).

***

## 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)

```text liquid theme={null}
{% if true or false and false %}
  This is true.
{% endif %}
```

### `if`, `elsif`, `else`

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

### `unless`

```text liquid theme={null}
{% 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.

```text liquid theme={null}
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](https://strftime.net/). A entrada usa o mesmo formato que Ruby's [Time.parse](https://ruby-doc.org/stdlib-2.4.1/libdoc/time/rdoc/Time.html).

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](./time-operators). Por exemplo, uma tag pode parecer com: `bill_due : 1687968776`

```text liquid theme={null}
{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}
```

```text Result theme={null}
Wed, Jun 28, 23
```

```text liquid theme={null}
{{ bill_due | date: "%Y" }}
```

```text Result theme={null}
2023
```

Formatação de data funciona em strings se elas contiverem datas bem formatadas.

```text liquid theme={null}
{{ "March 14, 2016" | date: "%b %d, %y" }}
```

```text Result theme={null}
Mar 14, 16
```

Para obter a hora atual, passe a palavra especial `now` (ou `today`) junto com o filtro date.

```text liquid theme={null}
This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
```

```text Result theme={null}
This message was sent at 2022-11-02 14:39.
```

<Info>
  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.
</Info>

### `capitalize`

Este filtro torna a primeira letra de uma string maiúscula e converte os caracteres restantes em minúsculas.

```text liquid theme={null}
{{ "my GREAT title" | capitalize }}
```

```text Result theme={null}
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.

```text liquid theme={null}
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
```

```text Result theme={null}
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.

```text liquid theme={null}
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
```

```text Result theme={null}
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](https://shopify.github.io/liquid/tags/iteration/).

```text liquid theme={null}
{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    Sorry, we're sold out of all products.
  {% endfor %}
```

```json Request Body theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "custom_data": {
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}
```

```text Result theme={null}
- Sweater
- Hat
- Shirt

(Se message.custom_data.products estiver vazio)
Desculpe, estamos sem estoque de todos os produtos.
```

<Warning>
  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`
</Warning>

### `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.

```text Data theme={null}
great_numbers = [1,2,3,4,5,6]
```

```text liquid theme={null}
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
```

```text Result theme={null}
1 2
```

Para iniciar o loop no índice especificado, adicione um valor de offset:

```text Data theme={null}
great_numbers = [1,2,3,4,5,6]
```

```text liquid theme={null}
{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

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

```text Result theme={null}
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`.

```text Data theme={null}
products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]
```

```text liquid theme={null}
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 %}
```

```text Result theme={null}
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.

```text liquid theme={null}
Hello {{ name | default: "there" }}!
```

```text Result (name = "Jon") theme={null}
Hello Jon!
```

```text Result (name está vazio) theme={null}
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.

```text liquid theme={null}
{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}
```

```text Result (name = "Jon") theme={null}
Jon, shop your favorites!
```

```text Result (name está vazio) theme={null}
Shop your favorites!
```

<Warning>
  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`.
</Warning>

### 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](https://shopify.github.io/liquid/basics/whitespace/) 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"](https://shopify.dev/docs/api/liquid/tags/raw).

```json theme={null}
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}
```

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Personalização de mensagens" icon="wand-magic-sparkles" href="./message-personalization">
    Visão geral de todas as opções de personalização, incluindo Liquid, Data Feeds e eventos personalizados.
  </Card>

  <Card title="Data Feeds" icon="database" href="./data-feeds">
    Puxe dados em tempo real de suas APIs para mensagens no momento do envio.
  </Card>

  <Card title="Tags" icon="tag" href="./add-user-data-tags">
    Armazene pares chave-valor em usuários para segmentação e personalização Liquid.
  </Card>

  <Card title="Templates" icon="file-lines" href="./templates">
    Crie templates de mensagens reutilizáveis com personalização Liquid integrada.
  </Card>
</Columns>