Variáveis de contexto
Variáveis de contexto são dados temporários que você pode criar e usar durante a jornada de um usuário em um Canvas específico. Elas permitem personalizar postergações, segmentar usuários dinamicamente e enriquecer o envio de mensagens sem alterar permanentemente as informações do perfil do usuário. As variáveis de contexto existem apenas dentro da sessão do Canvas e não persistem entre Canvas diferentes nem fora da sessão.
Como funcionam as variáveis de contexto
Você pode definir as variáveis de contexto de duas maneiras:
- Na entrada do Canvas: Quando os usuários entram em um Canvas, os dados do evento ou do disparo por API podem preencher automaticamente as variáveis de contexto.
- Em uma etapa de Contexto: Você pode definir ou atualizar as variáveis de contexto manualmente dentro do Canvas adicionando uma etapa de Contexto.
Cada variável de contexto inclui:
- Um nome (como
flight_timeousubscription_renewal_date) - Um tipo de dados (como número, string, horário ou array)
- Um valor que você atribui usando Liquid ou a ferramenta Adicionar personalização.
Depois de definida, você pode usar uma variável de contexto em todo o Canvas, referenciando-a neste formato: {{context.${example_variable_name}}}.
Por exemplo, {{context.${flight_time}}} pode retornar o horário do voo agendado do usuário.
Cada vez que um usuário entra no Canvas, mesmo que já tenha entrado antes, as variáveis de contexto são redefinidas com base nos dados de entrada mais recentes e na configuração do Canvas. Essa abordagem com estado permite que cada entrada no Canvas mantenha seu próprio contexto independente. Assim, os usuários podem ter vários estados ativos na mesma jornada, e cada estado mantém seu contexto específico.
Por exemplo, se um cliente tem dois voos marcados, ele terá dois estados de jornada separados em execução ao mesmo tempo, cada um com suas próprias variáveis de contexto do voo, como horário de partida e destino. Isso permite enviar lembretes personalizados sobre o voo das 14h para Nova York e, ao mesmo tempo, enviar atualizações diferentes sobre o voo das 8h de amanhã para Los Angeles. Dessa forma, cada mensagem continua relevante para a reserva específica.
Considerações
Você pode definir até 10 variáveis de contexto por etapa de Contexto. Cada nome de variável pode ter até 100 caracteres e deve usar apenas letras, números ou sublinhados.
As definições de variáveis de contexto podem ter até 10.240 caracteres. Se você passar variáveis de contexto para um Canvas acionado por API, elas compartilham o mesmo namespace das variáveis criadas em uma etapa de Contexto. Por exemplo, se você enviar uma variável purchased_item no objeto de contexto do endpoint /canvas/trigger/send, poderá referenciá-la como {{context.${purchased_item}}}. Se você redefinir essa variável em uma etapa de Contexto, o novo valor substituirá o valor da API na jornada desse usuário.
Você pode armazenar até 50 KB por etapa de Contexto, distribuídos em até 10 variáveis. Se o tamanho total de todas as variáveis em uma etapa ultrapassar 50 KB, as variáveis que excederem o limite não serão avaliadas nem armazenadas. Por exemplo, se você tiver três variáveis em uma etapa de Contexto:
- Variável 1: 30 KB
- Variável 2: 19 KB
- Variável 3: 2 KB
A variável 3 não é avaliada nem armazenada porque a soma das variáveis anteriores ultrapassa 50 KB.
Tipos de dados
As variáveis de contexto criadas ou atualizadas na etapa podem receber os seguintes tipos de dados.
As variáveis de contexto seguem os mesmos formatos esperados para tipos de dados que as propriedades de evento.
Quando você usa o tipo array, a Braze tenta analisar o valor como JSON, o que permite criar arrays de objetos. Se os objetos dentro dos seus arrays não forem JSON válido, o resultado será um array simples de strings.
Para objetos aninhados e arrays de objetos, use o filtro Liquid as_json_string. Se você estiver criando o mesmo objeto em uma etapa de Contexto, precisará renderizar o objeto usando as_json_string, por exemplo {{context.${object_array} | as_json_string }}
| Tipo de dados | Exemplo de nome da variável | Exemplo de valor |
|---|---|---|
| Booleano | loyalty_program | true |
| Número | credit_score | 740 |
| String | product_name | green_tea |
| Array | favorite_products | ["wireless_headphones", "smart_homehub", "fitness_tracker_swatch"] |
| Array (de objetos) | pet_details | [ |
| Hora (em UTC) | last_purchase_date | 2025-12-25T08:15:30:250-0800 |
| Objeto (achatado) | user_profile | { |
Por padrão, o tipo de dados de hora fica em UTC. Se você usar um tipo de dados string para armazenar um valor de hora, poderá definir a hora em outro fuso horário, como PST.
Por exemplo, se você for enviar uma mensagem a um usuário no dia anterior ao aniversário dele, salve a variável de contexto como tipo de dados de hora, porque há uma lógica Liquid associada ao envio no dia anterior. Por outro lado, se você for enviar uma mensagem de feriado no dia de Natal (25 de dezembro), não precisa referenciar a hora como uma variável dinâmica. Nesse caso, é preferível usar um tipo de dados string.
Para tipos de dados de objeto, você pode usar notação de ponto para especificar um caminho pelos dados. Por exemplo, se a sua etapa de Contexto definir uma variável de contexto order_summary com esta estrutura:
{
"shipping": {
"carrier": "overnight"
}
}
Em um filtro de Jornadas de público ou de Divisão de decisão, insira o caminho como o nome da variável de contexto usando notação de ponto (por exemplo, order_summary.shipping.carrier). Quando o filtro é avaliado, a Braze resolve esse caminho para o valor overnight.
No Liquid (por exemplo, em uma etapa de Mensagem), use {{context.${order_summary}.shipping.carrier}}.
Uso de variáveis de contexto
Você pode usar variáveis de contexto em qualquer lugar do Canvas onde usa Liquid, como nas etapas de Mensagem e Atualização do usuário. Para isso, selecione Adicionar personalização. Em mensagens no app e Banners nas etapas de Mensagem, você pode selecionar variáveis de contexto para definir quando a mensagem deve expirar.
Por exemplo, digamos que você queira avisar os passageiros sobre o acesso à sala VIP antes do próximo voo. Essa mensagem só deve ser enviada a quem comprou uma passagem de primeira classe. Uma variável de contexto é uma forma flexível de rastrear essa informação.
Os usuários entram no Canvas quando compram uma passagem aérea. Para determinar quem é elegível ao acesso à sala VIP, vamos criar uma variável de contexto chamada lounge_access_granted em uma etapa de Contexto. Depois, vamos referenciar essa variável de contexto nas etapas seguintes da jornada do usuário.
Nessa etapa de Contexto, vamos usar {{custom_attribute.${purchased_flight}}} para determinar se o tipo de voo comprado é first_class.
Em seguida, vamos criar uma etapa de Mensagem para direcionar os usuários em que {{context.${lounge_access_granted}}} é true. Essa mensagem será uma notificação por push com informações personalizadas sobre a sala VIP. Com base nessa variável de contexto, os passageiros elegíveis receberão as mensagens relevantes antes do voo.
- Passageiros com passagem de primeira classe receberão: “Aproveite o acesso exclusivo à sala VIP!”
- Passageiros com passagem executiva ou econômica receberão: “Faça upgrade do seu voo para ter acesso exclusivo à sala VIP.”
Você pode adicionar opções de postergação personalizadas com as informações da etapa de Contexto. Ou seja, você pode selecionar a variável que posterga os usuários.
Para jornadas de ação e critérios de saída
Você pode alavancar a comparação de filtros de propriedade com variáveis de contexto ou atributos personalizados nestas ações-gatilho: Realizar evento personalizado e Fazer compra. Esses gatilhos de ação também aceitam filtros de propriedade para propriedades básicas e aninhadas.
- Ao comparar com propriedades básicas, as comparações disponíveis correspondem ao tipo da propriedade definido pelo evento personalizado. Por exemplo, propriedades de string terão as comparações “exatamente igual” e “corresponde a regex”. Propriedades booleanas serão verdadeiras ou falsas.
- Ao comparar com propriedades aninhadas, os tipos não são predefinidos. Então, você pode selecionar comparações entre vários tipos de dados para booleanos, números, strings, hora e dia do ano, de forma semelhante às comparações de atributos personalizados aninhados. Se você selecionar um tipo de dado que não corresponde ao tipo real da propriedade aninhada no momento da comparação, o usuário não vai corresponder à etapa de jornadas de ação nem aos critérios de saída.
Exemplos de jornadas de ação
Para comparações de atributos personalizados, usamos o valor do atributo personalizado no momento em que a ação é realizada. Isso significa que o usuário não vai corresponder ao grupo de ação se não tiver esse atributo personalizado preenchido no momento da comparação, ou se o valor do atributo personalizado não corresponder às comparações de propriedade definidas. Isso vale mesmo que o usuário tivesse correspondido ao entrar na etapa de jornadas de ação.
A etapa de jornadas de ação a seguir está configurada para classificar os usuários que realizaram o evento personalizado Account_Created com a propriedade básica source em relação à variável de contexto app_source_variable.
A etapa de jornadas de ação a seguir está configurada para corresponder a propriedade básica brand do nome de produto específico shoes à variável de contexto promoted_shoe_brand.
Exemplos de critérios de saída
Os critérios de saída determinam que, em qualquer ponto da jornada do usuário no Canvas, ele vai sair do Canvas se:
- Realizar o evento personalizado Abandon Cart, e
- A propriedade básica Item in Cart corresponder ao valor da string da variável de contexto
cart_item_threshold.
Os critérios de saída determinam que, em qualquer ponto da jornada do usuário no Canvas, ele vai sair do Canvas se:
- Fizer uma compra específica do produto com o nome “book”, e
- A propriedade aninhada “loyalty_program” dessa compra for igual ao atributo personalizado “VIP” do usuário.
Definir uma expiração
Para Banners e mensagens no app em uma etapa de Mensagem do Canvas, selecione Uma duração após a etapa estar disponível para a expiração. Depois, ative Personalizar duração para definir a janela de disponibilidade a partir de uma variável de contexto. Por exemplo, você pode fazer isso para corresponder à duração de uma promoção ou reserva definida em uma etapa de Contexto.
Personalizar duração se aplica a essa opção de expiração baseada em duração. Se você escolher Em uma data e hora específicas, defina a expiração usando os controles de data e hora.
Postergações em jornadas de ação
Em uma etapa de jornadas de ação, em Janela de avaliação, ative Personalizar postergação para definir, a partir de uma variável de contexto, por quanto tempo os usuários ficam na etapa. Use essa opção quando o período de espera precisar variar para cada usuário com base em detalhes como nível ou região.
Filtros de variáveis de contexto
Você pode criar filtros que usam variáveis de contexto nas etapas de jornadas do público e divisão de decisão.
A lista Nome da variável de contexto inclui variáveis de etapas de Contexto e etapas de Agente. Para uma propriedade de entrada do Canvas, digite o nome dela e selecione Usar “ENTRY_PROPERTY_NAME“. Substitua ENTRY_PROPERTY_NAME pelo nome da propriedade de entrada que você digitou. Para uma propriedade aninhada, use a notação de ponto, como order.total.
Os filtros de variáveis de contexto estão disponíveis apenas para as etapas de jornadas do público e divisão de decisão.
As variáveis de contexto são declaradas e acessíveis apenas no escopo de um Canvas. Isso significa que elas não podem ser referenciadas em Segments. Os filtros de variáveis de contexto funcionam de forma semelhante nas etapas de jornadas do público e de divisão de decisão: as etapas de jornadas do público representam vários grupos, enquanto as etapas de divisão de decisão representam decisões binárias.
Assim como as variáveis de contexto do Canvas têm tipos predefinidos, as comparações entre variáveis de contexto e valores estáticos precisam ter tipos de dados correspondentes. O filtro de variável de contexto permite comparações entre vários tipos de dados para booleanos, números, strings, hora e dia do ano, de forma semelhante às comparações de atributos personalizados aninhados.
Veja um exemplo de filtro de variável de contexto que compara a variável de contexto product_name com a regex /braze/.
Filtros de dia do ano e hora para variáveis de contexto de data
Para usar filtros de comparação de Dia do ano ou Hora com uma variável de contexto:
- Adicione uma etapa de Contexto que defina uma variável de contexto como uma data do calendário (por exemplo, 23 de outubro de 2025).
- Adicione uma etapa de jornadas do público após a etapa de Contexto.
- Na etapa de jornadas do público, adicione um filtro que divida os usuários com base nessa variável de contexto.
- Escolha uma comparação da categoria Dia do ano ou Hora.
Se uma variável de contexto não tiver um tipo declarado, a Braze mostra todos os tipos de comparação disponíveis no menu suspenso, incluindo Dia do ano e Hora. Se a variável for declarada como do tipo hora na etapa de Contexto, apenas as comparações de Dia do ano e Hora são mostradas. Para outros tipos de dados com tipo conhecido (por exemplo, um atributo personalizado aninhado do tipo hora), apenas as comparações aplicáveis a esse tipo são mostradas.
Use o mesmo tipo de dado para a variável de contexto e para a comparação. Por exemplo, se a variável de contexto for do tipo hora, use comparações de hora (como “antes” ou “depois”). Usar tipos de dados diferentes (como comparações de string com uma variável de contexto de hora) pode causar comportamentos inesperados.
Escolhendo entre os tipos de filtro “Day of year” e “Time”: Ao filtrar variáveis de contexto que contêm datas, escolha o tipo de comparação correto com base em se a data se repete a cada ano. Use “Day of year” somente quando o ano não estiver incluído no valor que a variável de contexto produz.
- Use “Day of year” quando a data se repete a cada ano (por exemplo, aniversários, datas comemorativas ou feriados como o Natal). Esse tipo de comparação calcula com base no dia do ano (1-365/366), ignorando o componente do ano.
- Use “Time” quando a data for uma data absoluta que não se repete (por exemplo, datas de término de contrato, datas de compromissos ou datas de renovação de inscrição). Esse tipo de comparação calcula com base no timestamp completo, incluindo o ano.
Usar “Day of year” para datas absolutas pode produzir resultados incorretos ou inesperados porque o cálculo ignora o componente do ano. Por exemplo, se você estiver comparando uma data futura de término de contrato em abril para determinar se está dentro de 63 dias, usar “Day of year” pode corresponder incorretamente às datas porque compara apenas os números dos dias (119 vs 359) sem considerar que abril está na verdade a 188 dias de distância.
Comparação com variáveis de contexto ou atributos personalizados
Ao selecionar a opção Comparar com uma variável de contexto ou atributo personalizado, você pode criar filtros de variáveis de contexto que fazem comparações com variáveis de contexto definidas anteriormente ou com atributos personalizados do usuário. Isso é útil para fazer comparações dinâmicas por usuário, como o context disparado por API, ou para condensar uma lógica de comparação complexa definida em várias variáveis de contexto.
Digamos que você queira enviar um lembrete personalizado aos usuários após um período dinâmico de inatividade. Nesse caso, qualquer pessoa que não tenha feito login no seu app nos últimos três dias deve receber uma mensagem.
Você tem uma variável de contexto re_engagement_date definida como {{now | minus: 3 | append: ' days'}}. Observe que 3 days pode ser um valor variável, também armazenado como atributo personalizado do usuário. Então, se re_engagement_date for posterior a last_login_date (armazenado como atributo personalizado no perfil do usuário), o usuário receberá uma mensagem.
O filtro a seguir verifica se a variável de contexto reminder_date é anterior à variável de contexto appointment_deadline. Isso pode ajudar a agrupar usuários em uma etapa de jornadas do público para determinar se eles devem receber lembretes adicionais antes do prazo do agendamento.
Padronização da consistência de fuso horário
A maioria das propriedades de evento do tipo timestamp no Canvas já está em UTC, mas há algumas exceções. Com a adição do Canvas Context, todas as propriedades de evento padrão do tipo timestamp em Canvas baseados em ação passam a estar sempre em UTC. Essa mudança faz parte de um esforço maior para tornar mais previsível e consistente a experiência de edição de etapas e mensagens do Canvas. Ela afeta todos os Canvas baseados em ação, usem eles uma etapa de Contexto ou não.
Em todos os casos, recomendamos usar os filtros de fuso horário (time_zone) do Liquid para que os timestamps apareçam no fuso horário desejado. Veja um exemplo nesta pergunta frequente do artigo sobre a etapa de Contexto.