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 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 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 de voo agendado de um usuário e depois 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 gatilho 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 dado e um valor (definido usando Liquid ou a ferramenta Adicionar personalização). Quando definida, 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 digitar o nome da variável de contexto ou selecioná-lo no menu suspenso do 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 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.

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 Conteúdo conectado 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 chegando à próxima etapa conforme 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 Conteúdo conectado.

Sem Conteúdo conectado, as etapas de Contexto processam muito mais rápido 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 único (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.
• Variáveis passadas por gatilhos de API compartilham o mesmo namespace das criadas em etapas de Contexto; redefinir uma variável em uma etapa de Contexto sobrescreve o valor da API.

Para mais detalhes e uso avançado, consulte a 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 Caminhos 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, depois arraste e solte o componente da barra lateral, ou selecione o botão de mais 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 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 que use Liquid, como em etapas de Mensagem e Atualização de usuário, selecionando Add Personalization. No campo Context variable name, você também pode digitar o nome da variável de contexto ou selecioná-lo no menu suspenso do editor de etapas. Para um passo a passo completo, consulte a 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 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 sob intent_agent).

Para configuração de filtros, lógica de comparação e exemplos avançados, consulte a 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” 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.

Diretriz geral: A data se repete a cada ano? Sim → Use “Day of year”. Não → Use “Time”.

Pré-visualizando jornadas de usuários

Recomendamos testar e pré-visualizar suas jornadas de 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ê estiver pré-visualizando seu Canvas na seção Preview & Test Send do editor, o timestamp na pré-visualização da mensagem de teste não é padronizado para UTC porque esse painel gera pré-visualizações como strings. Isso significa que, se um Canvas estiver configurado para aceitar um objeto time, a pré-visualização da mensagem não reflete com precisão o que ocorre quando o Canvas está ativo. Para testar seu Canvas com mais precisão, recomendamos pré-visualizar as jornadas de usuários.

Observe quaisquer cenários comuns que criam 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 usando variáveis de contexto, e quaisquer comparações de etapas de público ou decisão que correspondam 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 foi criada corretamente, as etapas futuras do seu 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 consulta e definir o valor do horário da consulta como uma data passada, o e-mail de lembrete na sua etapa de Mensagem não será enviado.

Convertendo strings de Conteúdo conectado para JSON

Ao fazer uma chamada de Conteúdo conectado 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 Conteúdo conectado 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).

Por exemplo, se o tipo de dado 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.

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 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 exemplos de configuração para cada tipo de dado.

Atrasos no envio com Conteúdo conectado

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 passam para a próxima etapa, enquanto os usuários com falha 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

Em etapas do Canvas (incluindo etapas de Contexto), a Braze usa mecanismos de reprocessamento específicos do Canvas em vez do comportamento padrão de reprocessamento do Conteúdo conectado. Se uma chamada de Conteúdo conectado falhar:

• Para etapas de Mensagem, as chamadas de Conteúdo conectado podem ser reprocessadas até cinco vezes.
• Para todas as outras etapas, a Braze reprocessa a etapa aproximadamente 13 vezes com backoff exponencial.

Se todas as tentativas falharem, o usuário sai do Canvas.

A tag :retry usada no Conteúdo conectado padrão não se aplica a chamadas de Conteúdo conectado feitas dentro de etapas do Canvas. As etapas do Canvas têm sua própria lógica de reprocessamento otimizada para fluxos de trabalho do Canvas.

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 Conteúdo conectado é usado (e seu tempo de resposta)
• O tamanho do lote (padrão de 1.000 usuários por lote)

Se o seu endpoint de Conteúdo conectado tem limites de taxa, considere que as etapas de Contexto processam usuários sequencialmente dentro de cada lote, o que ajuda a respeitar os limites de taxa naturalmente. No entanto, múltiplos lotes são processados em paralelo, então garanta que seu endpoint possa lidar com solicitações simultâneas de múltiplos lotes.

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

Com o Contexto do Canvas 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. Observe que essa mudança impacta todos os Canvas baseados em ação, independentemente de o Canvas específico estar usando uma etapa de Contexto 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 Contexto do Canvas ficou disponível de forma geral?

Agora que o Contexto do Canvas está disponível de forma geral, os seguintes detalhes se aplicam:

• Todos os timestamps com um tipo datetime de propriedades de evento de gatilho em Canvas baseados em ação estão em UTC.
• Essa mudança impacta 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 impactados por essa mudança?

Não.

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

Sim, isso impacta 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 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 entre múltiplas etapas de Contexto. Por exemplo, imagine esta 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. Depois, 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 em todo o Canvas, e cada atualização afeta todas as etapas seguintes que referenciam essa variável.