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 formas:
- Na entrada do Canvas: quando os usuários entram em um Canvas, os dados do evento ou do gatilho de 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 dado (como número, string, horário ou array)
- Um valor que você atribui usando Liquid ou pela 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}}} poderia retornar o horário de voo programado 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, mantendo 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 no dia seguinte, 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 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 para a jornada daquele 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, as variáveis que ultrapassarem 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, precisará 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 |
|---|---|---|
| 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 | [ |
| Horário (em UTC) | last_purchase_date | 2025-12-25T08:15:30:250-0800 |
| Objeto (achatado) | user_profile | { |
Por padrão, o tipo de dado de horário está em UTC. Se você usar um tipo de dado string para armazenar um valor de horário, poderá definir o horário em um fuso horário diferente, como PST.
Por exemplo, se você estiver enviando uma mensagem a um usuário no dia anterior ao aniversário dele, salvaria a variável de contexto como tipo de dado de horário, pois há lógica Liquid associada ao envio no dia anterior. No entanto, se você estiver enviando uma mensagem de feriado no Natal (25 de dezembro), não precisaria referenciar o horário como uma variável dinâmica, então usar um tipo de dado string seria preferível.
Para tipos de dados de objeto, você pode usar notação de ponto para especificar um caminho pelos dados. Por exemplo, se sua etapa de Contexto definir uma variável de contexto order_summary com esta estrutura:
1
2
3
4
5
{
"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 for avaliado, a Braze resolverá 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 mensagens no app e Banners nas 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 deve ser enviada apenas para passageiros que compraram passagem 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 de avião. Para determinar a elegibilidade de acesso ao lounge, criaremos uma variável de contexto chamada lounge_access_granted em uma etapa de Contexto e, em seguida, 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 do lounge. 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 ao lounge VIP!”
- Passageiros de classe executiva e econômica receberão: “Faça upgrade do seu voo para ter acesso exclusivo ao lounge VIP.”
Você pode adicionar opções de postergação personalizadas com as informações da etapa de Contexto, o que significa que você pode selecionar a variável que posterga os usuários.
Para Jornadas de ação e critérios de saída
Você pode aproveitar filtros de comparação de propriedades 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 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 regex. Propriedades booleanas serão verdadeiro ou falso.
- 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, semelhante às comparações para atributos personalizados aninhados. Se você selecionar um tipo de dado que não corresponda ao tipo de dado real da propriedade aninhada no momento da comparação, o usuário não corresponderá à Jornada de ação ou aos critérios de saída.
Exemplos de Jornada 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 da Jornada 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 quando entrou na etapa de Jornada de ação.
A seguinte Jornada de ação 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 seguinte Jornada de ação 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 determinam que, em qualquer ponto da jornada do usuário no Canvas, ele 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 sairá do Canvas se:
- Fizer uma compra específica para o nome de produto “book”, e
- A propriedade aninhada dessa compra “loyalty_program” for igual ao atributo personalizado do usuário “VIP”.
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 expiração e, em seguida, ative Personalizar duração para controlar 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 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 de Jornada 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 ficam retidos 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 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, o que significa que não podem ser referenciadas em segmentos. Os filtros de variáveis de contexto funcionam de forma 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.
Assim 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, semelhante às comparações para atributos personalizados aninhados.
Use o mesmo tipo de dado para sua variável de contexto e comparação. Por exemplo, se sua variável de contexto for do tipo de dado de horário, use comparações de horário (como “antes” ou “depois”). Usar 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 “Dia do ano” e “Hora”: 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 “Dia do ano” 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 “Hora” 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 “Dia do ano” 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 “Dia do ano” 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.
Diretriz geral: A data se repete a cada ano? Sim → Use “Dia do ano”. Não → Use “Hora”.
Aqui está um exemplo de um filtro de variável de contexto comparando a variável de contexto product_name com o regex /braze/.
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. 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'}}. Note que 3 days pode ser um valor variável que também é armazenado como atributo personalizado do usuário. Então, se a re_engagement_date for posterior à last_login_date (armazenada como atributo personalizado no perfil do 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á esteja em UTC no Canvas, existem algumas exceções. Com a adição do Contexto do Canvas, todas as propriedades de evento de 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. Note que essa mudança impactará todos os Canvas baseados em ação, independentemente de o Canvas específico estar usando uma etapa de Contexto ou não.
Em todas as circunstâncias, recomendamos fortemente o uso de filtros Liquid de time_zone para que os timestamps sejam representados no fuso horário desejado. Você pode consultar esta pergunta frequente no artigo da etapa de Contexto para ver um exemplo.