Contexto

As etapas de Contexto permitem criar e atualizar uma ou mais variáveis para um usuário conforme ele avança por um Canvas. Por exemplo, se você tem um Canvas que gerencia descontos sazonais, pode usar uma variável de contexto para armazenar um código de desconto diferente cada vez que um usuário entra no Canvas.

Importante

A disponibilidade do Canvas Context varia por espaço de trabalho. Se Context não aparecer no menu de etapas do Canvas e o menu de personalização mostrar Canvas Entry Properties em vez de Context Variables, use canvas_entry_properties para dados de entrada. Entre em contato com o gerente da sua conta se precisar de acesso ao Canvas Context.

Como funciona

As etapas de Contexto permitem que você crie e use dados temporários durante a jornada de um usuário em um Canvas específico. Esses dados existem apenas dentro daquela jornada do Canvas e não persistem em outros Canvas ou fora da sessão.

As variáveis de contexto existem apenas para aquela jornada específica do Canvas. Elas não alteram permanentemente o perfil do usuário e não aparecem em outros Canvas. Isso as torna ideais para informações temporárias que são relevantes apenas para uma Campaign ou fluxo de trabalho específico.

Dica

Para uma referência completa sobre variáveis de contexto, incluindo tipos de dados, uso e práticas recomendadas, consulte a Referência de variáveis de contexto.

Dentro de uma etapa de Contexto, você pode definir ou atualizar até 10 variáveis de contexto. Essas variáveis podem ser usadas para personalizar postergações, segmentar usuários dinamicamente e enriquecer o envio de mensagens em todo o Canvas. Por exemplo, você poderia criar uma variável de contexto para o horário do voo agendado de um usuário e, em seguida, usá-la para definir postergações personalizadas e enviar lembretes.

Você pode definir variáveis de contexto de duas formas:

• Na entrada do Canvas: As propriedades do evento personalizado ou do disparo da API são automaticamente preenchidas como variáveis de contexto.
• Em uma etapa de Contexto: Defina ou atualize variáveis de contexto manualmente adicionando uma etapa de Contexto.

Cada variável de contexto requer um nome, um tipo de dado e um valor (definido usando Liquid ou a ferramenta Adicionar Personalização). Após definidas, você pode referenciar as variáveis de contexto em todo o Canvas usando Liquid, como {{context.${flight_time}}}. No campo Nome da variável de contexto, você também pode digitar o nome da variável de contexto ou selecioná-lo no menu suspenso no editor de etapas. Para mais detalhes, consulte a Referência de variáveis de contexto.

Cada entrada no Canvas redefine as variáveis de contexto com base nos dados de entrada mais recentes e na configuração do Canvas, permitindo que os usuários tenham múltiplas jornadas ativas, cada uma com seu próprio contexto. 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.

Processamento de usuários e agrupamento em lotes

As etapas de Contexto processam usuários em lotes para otimizar o desempenho. Quando os usuários entram em uma etapa de Contexto, a Braze os processa em lotes de 1.000 usuários por padrão. Esses lotes são processados em paralelo, mas dentro de cada lote, os usuários são processados sequencialmente.

Isso significa:

Exemplo: Se 3.500 usuários entram em uma etapa de Contexto com Connected Content que leva 650ms por usuário:

• A Braze cria 4 lotes de usuários (1.000, 1.000, 1.000 e 500 usuários neste exemplo).
• Cada lote processa os usuários sequencialmente, então um lote de 1.000 usuários leva aproximadamente 10,8 minutos (650 segundos; 1.000 × 650ms).
• Os lotes são concluídos em momentos diferentes, então os usuários vão passando para a próxima etapa conforme seu lote é finalizado.
• Os primeiros usuários podem chegar à próxima etapa vários minutos antes dos últimos usuários, dependendo do tamanho do lote e dos tempos de resposta do Connected Content.

Sem Connected Content, as etapas de Contexto processam muito mais rápido porque não há chamadas externas de API para aguardar.

Considerações

• Você pode definir até 10 variáveis de contexto por etapa de Contexto.
• Cada variável exige um nome exclusivo (apenas letras, números e underscores, com até 100 caracteres).
• O tamanho total de todas as variáveis em uma etapa não pode exceder 50 KB.
• As variáveis passadas por meio de gatilhos de API compartilham o mesmo namespace daquelas criadas nas etapas de Contexto; redefinir uma variável em uma etapa de Contexto substitui o valor da API.

Para saber mais e conhecer usos avançados, consulte Referência de variáveis de contexto.

Criando uma etapa de Contexto

Dica

Se Variável de contexto estiver disponível como filtro no seu espaço de trabalho, você não precisa de uma etapa de Contexto para referenciar propriedades do evento disparador nas etapas Jornadas do público ou Divisão de decisão. Você pode referenciar as propriedades diretamente nos grupos de filtro. Certifique-se de selecionar o tipo de dado correto.

Etapa 1: Adicionar uma etapa

Adicione uma etapa ao seu Canvas e, em seguida, arraste e solte o componente da barra lateral, ou selecione o botão de adição e selecione Context.

Etapa 2: Definir as variáveis

Nota

Você pode definir até 10 variáveis de contexto para cada etapa de Contexto.

Para definir uma variável de contexto:

1. Dê um nome à sua variável de contexto.
2. Selecione um tipo de dados.
3. Escreva uma expressão Liquid manualmente ou use Add Personalization para criar um snippet Liquid a partir de atributos pré-existentes.
4. Selecione Preview para verificar o valor da sua variável de contexto.
5. (Opcional) Para adicionar variáveis adicionais, selecione Add Context variable e repita as etapas 1 a 4.
6. Quando terminar, selecione Done.

Agora você pode usar sua variável de contexto em qualquer lugar que utilize Liquid, como nas etapas de Mensagem e Atualização de Usuário, selecionando Add Personalization. No campo Context variable name, você também pode inserir o nome da variável de contexto ou selecioná-lo no menu suspenso do editor de etapas. Para um passo a passo completo, consulte Referência de variáveis de contexto.

Importante

Ao referenciar variáveis de contexto, sempre use o formato {{context.${variable_name}}}.

Filtros de variáveis de contexto

Você pode criar filtros usando variáveis de contexto nas etapas Jornadas do Público e Divisão de Decisão.

Para direcionar usuários com base na resposta de uma etapa de Agente, adicione a etapa de Agente antes da sua etapa de Jornadas do Público ou Divisão de Decisão. A etapa de Agente armazena sua saída no contexto do Canvas, que você pode avaliar com filtros de variáveis de contexto nessas etapas de ramificação.

Se o agente retornar um objeto e você quiser filtrar por uma propriedade aninhada, insira o caminho no campo Context variable name usando notação de ponto em vez de apenas o nome da variável de nível superior (por exemplo, intent_agent.persona quando persona está aninhado em intent_agent).

Para configuração de filtros, lógica de comparação e exemplos avançados, consulte Referência de variáveis de contexto.

Importante

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.

Prévia das jornadas dos usuários

Recomendamos testar e visualizar as jornadas dos usuários para garantir que suas mensagens sejam enviadas ao público correto e que as variáveis de contexto sejam avaliadas com os resultados esperados.

Nota

Se você estiver visualizando seu Canvas na seção Preview & Test Send do editor, o registro de data e hora na prévia da mensagem de teste não é padronizado para UTC, pois esse painel gera prévias como strings. Isso significa que, se um Canvas estiver configurado para aceitar um objeto time, a prévia da mensagem não reflete com precisão o que ocorre quando o Canvas está ativo. Para testar seu Canvas da forma mais precisa, recomendamos visualizar as jornadas dos usuários.

Certifique-se de observar cenários comuns que criam variáveis de contexto inválidas. Ao visualizar a jornada do usuário, você pode ver os resultados de etapas de postergação personalizadas que usam variáveis de contexto, além de comparações em etapas de público ou de divisão de decisão que associam usuários a variáveis de contexto.

Se a variável de contexto for válida, você pode referenciá-la em todo o seu Canvas. No entanto, se a variável de contexto não tiver sido criada corretamente, as etapas seguintes do Canvas também não funcionarão corretamente. Por exemplo, se você criar uma etapa de contexto para atribuir aos usuários um horário de agendamento e definir o valor do horário como uma data passada, o e-mail de lembrete na etapa de mensagem não será enviado.

Convertendo strings de Connected Content para JSON

Ao fazer uma chamada de Connected Content em uma etapa de Contexto, o JSON retornado da chamada é avaliado como um tipo de dado string para consistência e prevenção de erros. Se você quiser converter essa string em JSON, faça a conversão usando as_json_string. Por exemplo:

1
2

{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

Solução de problemas

Variáveis de contexto inválidas

Uma variável de contexto é considerada inválida quando:

• Uma chamada a um Connected Content incorporado falha.
• A expressão Liquid em tempo de execução retorna um valor que não corresponde ao tipo de dados ou está vazio (nulo).
• A expressão Liquid chama {% abort_message() %}.

Por exemplo, se o tipo de dados da variável de contexto for Number, mas a expressão Liquid retornar uma string, ela será inválida.

Nessas circunstâncias:

• O usuário avança para a próxima etapa.
• A análise de dados da etapa do Canvas conta isso como Not Updated.

Durante a solução de problemas, monitore a métrica Not Updated para verificar se sua variável de contexto está sendo atualizada corretamente. Se a variável de contexto for inválida, seus usuários podem continuar no Canvas após a etapa de contexto, mas podem não se qualificar para etapas posteriores.

Consulte Tipos de dados para ver os exemplos de configuração de cada tipo de dados.

Uma variável de contexto também pode ser ignorada propositalmente com abort_message. Consulte Usando abort_message em uma variável de contexto.

Usando abort_message em uma variável de contexto

Você pode usar a tag Liquid abort_message no valor de uma variável de contexto para ignorar essa variável para alguns usuários. Em uma etapa de contexto, abort_message afeta apenas a variável na qual está inserida. Ela não interrompe a etapa e não remove o usuário do Canvas.

Quando o Liquid de uma variável de contexto chama abort_message para um usuário:

• A variável não é definida para esse usuário. Se uma etapa de contexto anterior já tiver definido essa variável, o usuário mantém o valor anterior.
• As outras variáveis na etapa ainda são avaliadas e definidas.
• Variáveis posteriores na mesma etapa que fazem referência a essa variável não recebem um novo valor dessa variável.
• O usuário avança para a próxima etapa.
• A análise de dados da etapa do Canvas conta a variável como Not Updated.

Por exemplo, esta variável é definida como true para usuários na França e ignorada para todos os demais:

1
2
3
4
5

{% if ${country} == "France" %}
  true
{% else %}
  {% abort_message("Not in France") %}
{% endif %}

Ao visualizar as jornadas dos usuários, uma variável ignorada aparece como “variable_name was not updated because the Liquid logic triggered an abort”.

Se etapas posteriores dependerem dessa variável, planeje para os usuários que não a têm definida. Por exemplo, você pode direcioná-los com uma etapa de jornada do público.

Nota

As interrupções de etapas de contexto não são registradas no registro de atividades de mensagens, e o motivo que você passa para abort_message não é exibido.

Atrasos no envio com Connected Content

Todos os usuários em um lote são processados antes que qualquer usuário avance. Após a conclusão do processamento do lote, os usuários bem-sucedidos seguem para a próxima etapa, enquanto os que falharam são reprocessados separadamente — os usuários bem-sucedidos não esperam que as tentativas de reprocessamento sejam concluídas antes de avançar.

Comportamento de reprocessamento

As chamadas de Connected Content em um Canvas são reprocessadas apenas quando a chamada inclui :retry.

• Etapas de contexto e de atualização de usuário: a Braze reprocessa a chamada de Connected Content no nível da etapa (até cinco vezes). Se todas as tentativas falharem, o usuário sai do Canvas.
• Etapas de mensagem: o Connected Content com :retry ainda usa o pipeline de envio de mensagens. Os destinatários ficam em espera na fila de envio enquanto a Braze reprocessa a chamada até cinco vezes. Se todas as tentativas falharem, a mensagem é cancelada e o usuário avança para a próxima etapa.

Para etapas de contexto e de atualização de usuário, determinados erros de etapa reprocessáveis — como uma falha na obtenção de código promocional ou um erro inesperado na etapa — podem disparar tentativas adicionais de reprocessamento no nível da etapa com backoff exponencial (aproximadamente 13 vezes) antes que a Braze remova o usuário do Canvas.

Para saber mais sobre a tag :retry, consulte Reprocessamento de Connected Content.

O tempo necessário para processar todos os usuários em uma etapa de contexto depende de:

• O número de usuários que entram na etapa
• Se o Connected Content é utilizado (e seu tempo de resposta)
• O tamanho do lote (padrão de 1.000 usuários por lote)

Se o seu endpoint de Connected Content tiver limites de frequência, considere que as etapas de contexto processam os usuários sequencialmente dentro de cada lote, o que ajuda a respeitar os limites de frequência naturalmente. No entanto, vários lotes são processados em paralelo, então garanta que seu endpoint consiga lidar com solicitações simultâneas de vários lotes.

Consistência de fuso horário

Para espaços de trabalho com Canvas Context, todas as propriedades de evento de timestamp padrão em Canvas baseados em ação estão em UTC. Esse comportamento se aplica independentemente de o Canvas usar uma etapa de Context ou não.

Importante

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 para ver um exemplo.

Perguntas frequentes

Como o Canvas Context afeta os timestamps?

Para espaços de trabalho com Canvas Context:

• Todos os timestamps com um tipo datetime de propriedades de eventos-gatilho em Canvas baseados em ação estão em UTC.
• Essa mudança afeta todos os Canvas baseados em ação, independentemente de o Canvas específico estar usando uma etapa de Context ou não.

Qual é o motivo dessa mudança?

Essa mudança faz parte de um esforço mais amplo para criar uma experiência mais previsível e consistente ao editar etapas e mensagens do Canvas.

Canvas disparados por API ou agendados são afetados por essa mudança?

Não.

Essa mudança afeta as propriedades de entrada do Canvas?

Sim, isso afeta canvas_entry_properties se a canvas_entry_property estiver sendo usada em um Canvas baseado em ação e o tipo da propriedade for time. Em todas as circunstâncias, recomendamos usar filtros Liquid time_zone para que os timestamps sejam representados no fuso horário desejado.

Veja um exemplo de como fazer isso:

Qual é um exemplo prático de como o novo comportamento de timestamp pode afetar minhas mensagens?

Digamos que temos um Canvas baseado em ação com o seguinte conteúdo em uma etapa de mensagem:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Isso resulta na seguinte mensagem:

1

Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!

Como nenhum fuso horário é especificado usando Liquid, o timestamp aqui está em UTC.

Para especificar um fuso horário claramente, podemos usar filtros Liquid time_zone assim:

1

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

Isso resulta na seguinte mensagem:

1

Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!

Como o fuso horário America/Los Angeles é especificado usando Liquid, o timestamp aqui está em PST.

O fuso horário preferido também pode ser enviado na carga útil das propriedades do evento e usado na lógica Liquid:

1
2
3
4

{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

Como as variáveis de contexto diferem das propriedades de entrada do Canvas?

As propriedades de entrada do Canvas são incluídas como variáveis de contexto do Canvas. Isso significa que você pode enviar propriedades de entrada do Canvas usando a API da Braze e referenciá-las em outras etapas, de forma semelhante ao uso de uma variável de contexto com o snippet Liquid.

As variáveis podem referenciar umas às outras em uma única etapa de Context?

Sim. Todas as variáveis em uma etapa de Context são avaliadas em sequência, o que significa que você pode ter as seguintes variáveis de contexto configuradas:

Isso também se aplica a múltiplas etapas de Context. Por exemplo, imagine a seguinte sequência:

1. Uma etapa de Context inicial cria uma variável chamada JobInfo com o valor job_title.
2. Uma etapa de mensagem referencia {{context.${JobInfo}}} e exibe job_title para o usuário.
3. Posteriormente, uma etapa de Context atualiza a variável de contexto, alterando o valor de JobInfo para job_description.
4. Todas as etapas subsequentes que referenciam JobInfo agora usam o valor atualizado job_description.

As variáveis de contexto usam seu valor mais recente ao longo do Canvas, e cada atualização afeta todas as etapas seguintes que referenciam essa variável.