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.

Como funciona

As etapas de Contexto permitem criar e usar dados temporários durante a jornada de um usuário em um Canvas específico. Esses dados existem apenas dentro dessa 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 o perfil do usuário permanentemente e não aparecem em outros Canvas. Isso as torna ideais para informações temporárias que são relevantes apenas para uma campanha 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 disparador de 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 dados e um valor (definido usando Liquid ou a ferramenta Adicionar personalização). Uma vez definidas, você pode referenciar variáveis de contexto em todo o Canvas usando Liquid, como {{context.${flight_time}}}. No campo Context variable name, você também pode inserir 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 com seu próprio contexto. Por exemplo, se um cliente tem dois voos próximos, ele terá dois estados de jornada separados em execução 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.

Processamento de usuários e 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 650 ms 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 × 650 ms).
• Os lotes são concluídos em momentos diferentes, então os usuários vão chegando à próxima etapa à medida que seu lote é finalizado.
• Os primeiros usuários podem alcançar a 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 são processadas muito mais rapidamente porque não há chamadas de API externas para aguardar.

Considerações

• Você pode definir até 10 variáveis de contexto por etapa de Contexto.
• Cada variável requer 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 disparos de API compartilham o mesmo namespace daquelas criadas nas etapas de Contexto. Redefinir uma variável em uma etapa de Contexto sobrescreve o valor da API.

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

Criando uma etapa de Contexto

Dica

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 com o filtro Variável de contexto. 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 Contexto.

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 dado.
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-4.
6. Quando terminar, selecione Done.

Agora você pode usar sua variável de contexto em qualquer lugar onde usar Liquid, como em 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 em etapas de Audience Paths 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 etapa de Audience Paths ou divisão de decisão. A etapa de Agente armazena sua saída no contexto do Canvas, que pode ser avaliada 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 sob 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 pré-visualizar as jornadas dos usuários para garantir que suas mensagens sejam enviadas ao público certo e que as variáveis de contexto sejam avaliadas com os resultados esperados.

Nota

Se você está pré-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 com maior precisão, recomendamos pré-visualizar as jornadas dos usuários.

Observe todos os cenários comuns que geram variáveis de contexto inválidas. Ao pré-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 qualquer comparação de público ou divisão de decisão que associe 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 seu Canvas também não funcionarão como esperado. Por exemplo, se você criar uma etapa de contexto para atribuir um horário de consulta aos usuários e definir o valor do horário da consulta como uma data no passado, o e-mail de lembrete na sua etapa de mensagem não será enviado.

Convertendo strings de Connected Content em 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, use 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 dado ou está vazio (nulo).
• A expressão Liquid chama {% abort_message() %}.

Por exemplo, se o tipo de dado da variável de contexto é Number, mas a expressão Liquid retorna uma string, ela é 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.

Ao solucionar 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 poderão continuar no Canvas além da 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 dado.

Uma variável de contexto também pode ser intencionalmente ignorada 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 em que 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 dela.
• 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 dependem 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 na etapa de contexto não são registradas no Message Activity Log, e o motivo informado em 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 aguardam o sucesso das novas tentativas antes de avançar.

Comportamento de novas tentativas

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 são mantidos 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, certos erros reprocessáveis no nível da etapa — como uma falha na busca de código promocional ou um erro inesperado na etapa — podem disparar novas tentativas adicionais 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 Novas tentativas 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 entrando 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 possui 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, múltiplos lotes são processados em paralelo, então certifique-se de que seu endpoint pode lidar com requisições simultâneas de múltiplos lotes.

Padronização de consistência de fuso horário

Com o Canvas Context disponível de forma geral, todas as propriedades de evento de timestamp padrão em Canvas baseados em ação estão 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. Essa mudança impacta todos os Canvas baseados em ação, independentemente de o Canvas específico estar usando uma etapa de Context ou não.

Importante

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

Perguntas frequentes

O que mudou desde que o Canvas Context ficou disponível para todos?

Agora que o Canvas Context está disponível para todos, os seguintes detalhes se aplicam:

• Todos os carimbos de data/hora com um tipo datetime das propriedades de evento-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 contexto 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 todos os casos, recomendamos usar filtros Liquid time_zone para que os carimbos de data/hora 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 carimbo de data/hora 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 carimbo de data/hora 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 carimbo de data/hora 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 contexto?

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

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

1. Uma etapa de contexto 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 contexto 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, com cada atualização afetando todas as etapas seguintes que referenciam essa variável.