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 de um usuário. As variáveis de contexto existem apenas dentro da sessão do Canvas e não persistem entre Canvas diferentes ou fora da sessão.
Como as variáveis de contexto funcionam
As variáveis de contexto podem ser definidas de duas maneiras:
- Na entrada do Canvas: Quando os usuários entram em um Canvas, os dados do evento ou do disparo via API podem preencher automaticamente as variáveis de contexto.
- Em uma etapa de Contexto: Você pode definir ou atualizar 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 pela ferramenta Add Personalization.
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}}} poderia retornar o horário programado do voo do usuário.
Cada vez que um usuário entra no Canvas — mesmo que já tenha entrado antes — as variáveis de contexto serã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, possibilitando que os usuários tenham múltiplos estados ativos dentro da mesma jornada enquanto retêm o contexto específico de cada estado.
Por exemplo, se um cliente tem dois voos próximos, ele terá dois estados de jornada separados rodando simultaneamente — cada um com suas próprias variáveis de contexto específicas do voo, como horário de partida e destino. Isso permite que você envie lembretes personalizados sobre o voo das 14h para Nova York enquanto envia atualizações diferentes sobre o voo das 8h para Los Angeles amanhã, de modo que cada mensagem permaneça 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 underscores.
As definições de variáveis de contexto podem ter até 10.240 caracteres. Se você passar variáveis de contexto para um Canvas disparado 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 endpoint /canvas/trigger/send no objeto de contexto, você pode 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 para a 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 exceder 50 KB, quaisquer variáveis que ultrapassem 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 será avaliada nem armazenada porque a soma das variáveis anteriores excede 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 têm os mesmos formatos esperados para tipos de dados que as propriedades de evento.
Ao usar o tipo array, a Braze tenta analisar o valor como JSON, o que permite que arrays de objetos sejam criados com sucesso. 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, será necessário renderizar o objeto usando as_json_string, como {{context.${object_array} | as_json_string }}
| Tipo de dado | Exemplo de nome de variável | Exemplo de valor |
|---|---|---|
| Boolean | 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 dado de hora está em UTC. Se você usar um tipo de dado string para armazenar um valor de hora, poderá definir a hora em um fuso horário diferente, como PST.
Por exemplo, se você estiver enviando uma mensagem para um usuário no dia anterior ao aniversário dele, salvaria a variável de contexto como um tipo de dado de hora, porque há lógica Liquid associada ao envio no dia anterior. No entanto, se você estiver enviando uma mensagem de feriado no dia de Natal (25 de dezembro), não precisaria referenciar a hora como uma variável dinâmica, então usar um tipo de dado string seria preferível.
Para tipos de dado 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 do público ou 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.
Em Liquid (como em uma etapa de mensagem), use {{context.${order_summary}.shipping.carrier}} em vez disso.
Usando variáveis de contexto
Você pode usar variáveis de contexto em qualquer lugar onde usar Liquid em um Canvas, como nas etapas de Mensagem e Atualização de Usuário, selecionando Adicionar Personalização. Para In-App Messages e Banners em etapas de Mensagem, você pode selecionar variáveis de contexto para determinar quando a mensagem deve expirar.
Por exemplo, digamos que você queira notificar passageiros sobre o acesso ao lounge VIP antes do próximo voo. Essa mensagem só deve ser enviada a passageiros que compraram um bilhete de primeira classe. Uma variável de contexto é uma forma flexível de rastrear essa informação.
Os usuários entrarão no Canvas quando comprarem uma passagem aérea. Para determinar a elegibilidade de acesso ao lounge, criaremos uma variável de contexto chamada lounge_access_granted em uma etapa de Contexto, e então referenciaremos essa variável de contexto nas etapas subsequentes da jornada do usuário.
Nesta etapa de Contexto, usaremos {{custom_attribute.${purchased_flight}}} para determinar se o tipo de voo comprado é first_class.
Em seguida, criaremos uma etapa de Mensagem para direcionar usuários onde {{context.${lounge_access_granted}}} é true. Essa mensagem será uma notificação por push que inclui informações personalizadas sobre o lounge. Com base nessa variável de contexto, os passageiros elegíveis receberão as mensagens relevantes antes do voo.
- Passageiros com bilhete de primeira classe receberão: “Aproveite o acesso exclusivo ao lounge VIP!”
- Passageiros de classe executiva e econômica receberão: “Faça upgrade do seu voo para acesso exclusivo ao lounge VIP.”
Você pode adicionar opções de postergação personalizada 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 filtros de comparação de propriedades com variáveis de contexto ou atributos personalizados nestas ações-gatilho: Realizar Evento Personalizado e Fazer Compra. Essas ações-gatilho também suportam filtros de propriedade para propriedades básicas e aninhadas.
- Ao comparar com propriedades básicas, as comparações disponíveis corresponderão ao tipo da propriedade definida pelo evento personalizado. Por exemplo, propriedades de string terão correspondência exata e correspondência por regex. Propriedades booleanas serão verdadeiras ou falsas.
- Ao comparar com propriedades aninhadas, os tipos não são pré-definidos, então você pode selecionar comparações entre múltiplos tipos de dados para booleanos, números, strings, horário e dia do ano, de forma semelhante às comparações para atributos personalizados aninhados. Se você selecionar um tipo de dados que não corresponde ao tipo de dados real da propriedade aninhada no momento da comparação, o usuário não corresponderá à etapa de jornadas de ação ou aos critérios de saída.
Exemplos de jornadas de ação
Para comparações de atributos personalizados, usaremos o valor do atributo personalizado no momento em que a ação é realizada. Isso significa que um usuário não 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 é válido mesmo que o usuário tivesse correspondido quando entrou na etapa de jornadas de ação.
A etapa de jornadas de ação a seguir está configurada para classificar usuários que realizaram o evento personalizado Account_Created com a propriedade básica source para a 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 para o nome de produto específico shoes a uma variável de contexto promoted_shoe_brand.
Exemplos de critérios de saída
Os critérios de saída estabelecem que, em qualquer ponto da jornada do usuário no Canvas, ele sairá do Canvas se:
- Ele 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 estabelecem que, em qualquer ponto da jornada do usuário no Canvas, ele sairá do Canvas se:
- Ele fizer uma compra específica para o nome de produto “book”, e
- A propriedade aninhada dessa compra “loyalty_program” for igual ao atributo personalizado “VIP” do usuário.
Definir uma expiração
Para Banners e In-App Messages em uma etapa de Mensagem do Canvas, selecione Uma duração após a etapa estar disponível para expiração, e então ative Personalizar duração para definir a janela de disponibilidade a partir de uma variável de contexto — por exemplo, para corresponder a uma promoção ou duração de reserva de uma etapa de Contexto.
Personalizar duração se aplica à 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 de jornadas de ação
Em uma etapa de jornadas de ação, em Janela de Avaliação, ative Personalizar postergação para definir por quanto tempo os usuários são mantidos na etapa a partir de uma variável de contexto. Use isso quando o período de espera deve variar por 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 declaradas anteriormente nas etapas de jornadas do público e divisão de decisão.
Os filtros de variáveis de contexto estão disponíveis apenas para 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, o que significa que não podem ser referenciadas em Segments. Os filtros de variáveis de contexto funcionam de maneira semelhante nas etapas de jornadas do público e divisão de decisão — as etapas de jornadas do público representam múltiplos grupos, enquanto as etapas de divisão de decisão representam decisões binárias.
De forma semelhante a como as variáveis de contexto do Canvas têm tipos pré-definidos, as comparações entre variáveis de contexto e valores estáticos devem ter tipos de dados correspondentes. O filtro de variável de contexto permite comparações entre múltiplos tipos de dados para booleanos, números, strings, horário e dia do ano, de forma semelhante às comparações para atributos personalizados aninhados.
Aqui está um exemplo de filtro de variável de contexto comparando a variável de contexto product_name ao regex /braze/.
Filtros de dia do ano e horário para variáveis de contexto de data
Para usar os filtros de comparação Dia do Ano ou Horário com uma variável de contexto:
- Adicione uma etapa de Contexto que defina uma variável de contexto como uma data de 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 Horário.
Se uma variável de contexto não tiver tipo declarado, a Braze mostra todos os tipos de comparação disponíveis no menu suspenso, incluindo Dia do Ano e Horário. Se a variável for declarada como tipo time na etapa de Contexto, apenas as comparações de Dia do Ano e Horário serão exibidas. Para outros tipos de dados com tipo conhecido (por exemplo, um atributo personalizado aninhado com tipo time), apenas as comparações aplicáveis a esse tipo serão exibidas.
Use o mesmo tipo de dados para sua variável de contexto e comparação. Por exemplo, se sua variável de contexto for do tipo time, use comparações de horário (como “antes” ou “depois”). O uso de tipos de dados incompatíveis (como comparações de string com uma variável de contexto de horário) pode causar comportamento inesperado.
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.
Comparando com variáveis de contexto ou atributos personalizados
Ao selecionar o botão Comparar com uma variável de contexto ou atributo personalizado, você pode construir filtros de variáveis de contexto que comparam com variáveis de contexto definidas anteriormente ou atributos personalizados do usuário. Isso pode ser útil para realizar comparações dinâmicas por usuário, como context disparado por API, ou para condensar lógica de comparação complexa definida entre variáveis de contexto.
Digamos que você queira enviar um lembrete personalizado aos usuários após um período dinâmico de inatividade, que inclui qualquer pessoa que não tenha feito login no seu app nos últimos três dias e que deve receber uma mensagem.
Você tem uma variável de contexto re_engagement_date definida como {{now | minus: 3 | append: ' days'}}. Note que 3 days pode ser um valor variável que também está armazenado como um atributo personalizado do usuário. Então, se a re_engagement_date for posterior à last_login_date (armazenada como um atributo personalizado no perfil de usuário), a mensagem será enviada.
O filtro a seguir compara a variável de contexto reminder_date para ser 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 compromisso.
Padronização de consistência de fuso horário
Embora a maioria das propriedades de evento que usam o tipo timestamp já estejam em UTC no Canvas, existem algumas exceções. Com a adição do Canvas Context, todas as propriedades de evento timestamp padrão em Canvas baseados em ação serão consistentemente em UTC. Essa mudança faz parte de um esforço mais amplo para garantir uma experiência mais previsível e consistente ao editar etapas e mensagens do Canvas. Observe que essa mudança impactará todos os Canvas baseados em ação, independentemente de o Canvas específico estar usando uma etapa de Context ou não.
Em todas as circunstâncias, recomendamos fortemente o uso de filtros Liquid time_zone para que os timestamps sejam representados no fuso horário desejado. Você pode consultar esta pergunta frequente no artigo da etapa de Context para ver um exemplo.