> ## 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.
# Personalização
> Escolha o método de personalização correto no OneSignal. Compare Properties, Custom Events, API custom_data, Data Feeds e uploads de CSV para enviar mensagens dinâmicas usando sintaxe Liquid.
A personalização permite que você envie mensagens que incluem dados dinâmicos — como o nome do usuário, itens do carrinho, saldo da conta, detalhes de reserva ou uma senha de uso único.
Este guia ajuda você a escolher o método de personalização correto com base em:
* Onde seus dados estão armazenados
* Se eles devem persistir
* Como a mensagem é acionada
***
## Como funciona a personalização
A personalização no OneSignal tem duas partes:
1. **Sintaxe Liquid** – define como os valores são renderizados na sua mensagem
2. **Uma fonte de dados** – determina de onde o valor vem
No momento do envio, o OneSignal resolve suas variáveis Liquid usando a fonte de dados selecionada.
Liquid controla a formatação e a lógica (variáveis, loops, condicionais). A fonte de dados determina quais valores estão disponíveis.
**Exemplo:**
```liquid Liquid theme={null}
Hi {{ user.tags.first_name }},
Your verification code is {{ message.custom_data.otp }}.
```
* `user.tags.first_name` é uma property armazenada
* `message.custom_data.otp` é passado pelo campo `custom_data` da API
***
## Campos suportados por tipo de mensagem
* Subject, Reply-to e Pre-header
* Message Body
* Substituição de imagem em blocos HTML. Exemplo: ``
* Ações de bloco de botão como URLs, Mail to e outros campos.
* Title (`headings`), Subtitle, Body (`contents`)
* Image URL
* Launch URL. Exemplo: `https://example.com/{{last_category_viewed}}`
* `data` adicional não suporta sintaxe Liquid.
* Message Body (`contents`)
Apenas substituição de Tag é suportada neste momento.
A tag deve ser definida antes do usuário abrir o app para iniciar uma nova sessão. As tags disponíveis estão no [método `getTags`](./mobile-sdk-reference#gettags).
**Editor de blocos:**
* Substituição de tag funciona em Blocos de Texto, Botão e Imagem.
**Editor HTML:**
* Substituição de tag funciona em:
* Tags Header `` e `
`. Exemplo: `
Hello {{first_name}}!
`
* Atributos de elemento: `["src", "href", "action", "data"]`. Exemplo: ``
Veja [APIs JavaScript de mensagens in-app](./in-app-message-api) para mais detalhes e exemplos.
* Dentro das propriedades `event_updates`, `contents` e `headings`.
***
## Fontes de dados
O OneSignal suporta cinco fontes de dados para personalização. Use a tabela abaixo para identificar qual fonte se adequa ao seu caso de uso e, em seguida, leia a seção detalhada para obter orientação de implementação.
| Fonte de dados | O que é | Quando usar | Persistida | Disponível em Journeys |
| ----------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- | ---------------------- |
| [**Properties**](#properties) | Tags, External ID, dados de subscription, campos do app | Valores reutilizáveis armazenados no OneSignal (nome, plano, preferências) | Sim | Sim |
| [**Custom Events**](#custom-events) | Propriedades de eventos capturadas na entrada da Journey ou Wait Until | Personalização comportamental dentro de Journeys | Por evento | Somente Journey |
| [**API `custom_data`**](#api-custom_data) | Pares chave-valor passados na API Create Message | Valores de uso único ou sensíveis (OTP, links seguros, itens do carrinho) | Não | Não |
| [**Data Feeds**](#data-feeds) | Chamada de API ao vivo feita no momento do envio | Valores que mudam frequentemente (preços, estoque, saldo da conta) | Não | Sim |
| [**Dynamic Content CSV**](#dynamic-content-csv) | CSV enviado no painel | Campanhas em massa com conteúdo por destinatário | Por envio | Não |
**Erros comuns a evitar**
* Usar Properties (Tags) para valores de uso único como OTPs ou códigos de verificação — use `custom_data` em vez disso
* Esperar que `custom_data` esteja disponível em Journeys ou mensagens futuras — ele existe apenas para a requisição API atual
* Presumir que propriedades de Custom Events estão disponíveis fora da entrada de Journey acionada por evento ou de um passo Wait Until
* Usar Data Feeds para dados estáticos que raramente mudam — use Properties em vez disso
### Properties
Properties incluem tags de usuário, External ID, dados de subscription e campos no nível do app.
Elas são:
* Persistentes
* Reutilizáveis
* Disponíveis em mensagens, templates, [Journey webhooks](./journeys-webhook) e [Event Streams](./event-streams).
**Use Properties quando:**
* O valor existe no OneSignal
* O valor é persistente
* Você o reutiliza em campanhas
Aprenda como referenciar dados persistentes armazenados como properties.
***
### Custom Events
[Custom Events](./custom-events) podem personalizar mensagens dentro de [Journeys](./journeys-overview) usando propriedades de eventos.
Quando um evento **inicia uma Journey** ou **corresponde a uma condição Wait Until**, o OneSignal armazena esse evento para que suas propriedades possam ser referenciadas em templates de mensagem usando Liquid.
**Quando usar Custom Events:**
* Mensagens acionadas por eventos com Journeys
* A mensagem deve refletir dados específicos do evento
Apenas eventos que acionam a entrada na Journey ou um passo Wait Until são armazenados para personalização. Eventos enviados fora desses momentos não estão disponíveis para mensagens de Journey.
Guia completo para usar propriedades de eventos em Journeys.
***
### API `custom_data`
O campo `custom_data` na [API Create Message](/reference/create-message) permite que você envie valores específicos por mensagem a partir do seu backend.
Esses dados:
* Existem apenas para a requisição atual
* Não são armazenados no OneSignal
* Não estão disponíveis em Journeys
**Use `custom_data` quando:**
* Enviar valores de uso único ou sensíveis (OTP, links seguros)
* Passar arrays (itens do carrinho, linhas de pedido, pontuações de ranking)
* Enviar mensagens transacionais ou acionadas por API
Aprenda como passar dados transitórios de personalização.
***
### Data Feeds
[Data Feeds](./data-feeds) chamam sua API no momento do envio e injetam a resposta na sua mensagem.
**Quando usar Data Feeds:**
* Você precisa do valor mais recente na entrega
* Os dados estão no seu backend
* O valor pode mudar entre envios
Obtenha dados em tempo real do backend nas mensagens no momento do envio.
***
### Dynamic Content CSV
Faça upload de um arquivo CSV no painel do OneSignal e referencie seus valores usando Liquid.
**Use CSV quando:**
* Personalizar diferentes seções de uma campanha em massa para cada destinatário
* Traduções ou dados personalizados para cada destinatário são exportáveis para um arquivo CSV
* Você não quer usar a API
Personalize campanhas pelo painel usando uploads de CSV.
***
## Guias detalhados
Use os guias abaixo para detalhes de implementação passo a passo e exemplos avançados.
Aprenda como inserir dados dinâmicos em mensagens usando Liquid. Abrange variáveis, condicionais, loops, filtros, formatação e padrões comuns de personalização.
Obtenha dados em tempo real de suas próprias APIs no momento do envio. Use Data Feeds quando o conteúdo da mensagem depende de valores do backend em tempo real, como saldos, disponibilidade ou preços.
Personalize mensagens de Journey usando propriedades de eventos capturadas quando os usuários entram ou avançam em uma Journey. Ideal para fluxos de trabalho comportamentais e orientados por eventos.
Use properties armazenadas de usuários, subscriptions, mensagens e apps para personalizar conteúdo em mensagens, templates, Journey webhooks e Event Streams.
Passe dados por mensagem e transitórios do seu backend usando a API Create Message. Ideal para OTPs, carrinhos, arrays e personalização transacional em massa.
Faça upload de arquivos CSV no painel para personalizar campanhas em escala. Cada linha é mapeada para um destinatário e pode ser referenciada usando Liquid.
### Tutoriais
Estes guias mostram como implementar personalização na prática.
Envie mensagens de verificação seguras usando senhas de uso único, magic links ou URLs personalizadas com personalização orientada por API.
Crie uma Journey automatizada que detecta atividade de carrinho, aguarda inatividade, envia um lembrete personalizado e finaliza a jornada do usuário imediatamente após a compra.
Envie mensagens de confirmação e recuperação de reservas usando Custom Events, Journeys e Data Feeds com base no status da reserva em tempo real.
Aprenda como enviar recibos, alertas, confirmações e outras mensagens transacionais em diversos canais usando APIs e automação.
Veja exemplos práticos de uso de tags e properties para personalizar mensagens in-app para diferentes usuários e segmentos.