Ir para o conteúdo

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

Uma etapa de Contexto como a primeira etapa de um Canvas.

As etapas de Contexto permitem criar e usar dados temporários durante a jornada de um usuário por um Canvas específico. Esses dados existem apenas dentro dessa jornada do Canvas. Eles não persistem em outros Canvas nem fora da sessão.

As variáveis de contexto existem apenas naquela jornada específica do Canvas. Elas não alteram o perfil do usuário de forma permanente e não aparecem em outros Canvas. Por isso, são ideais para informações temporárias que só importam para uma campanha ou um fluxo de trabalho específico.

Em 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 de forma dinâmica e enriquecer as mensagens ao longo do Canvas. Por exemplo, você pode criar uma variável de contexto com o horário do 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 disparo por API são preenchidas automaticamente 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 exige um nome, um tipo de dado e um valor (definido com Liquid ou com a ferramenta Adicionar personalização). Depois de 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 inserir o nome da variável de contexto ou selecioná-lo no menu suspenso do editor da etapa. Para saber mais, 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. Assim, os usuários podem ter várias jornadas ativas, cada uma com seu próprio contexto. Por exemplo, se um cliente tem dois voos marcados, ele terá dois estados de jornada separados rodando ao mesmo tempo—cada um com suas próprias variáveis de contexto específicas do voo, como horário de partida e destino. Então, você pode enviar lembretes personalizados sobre o voo das 14h para Nova York e, ao mesmo tempo, enviar atualizações diferentes sobre o voo de amanhã às 8h para Los Angeles. Dessa forma, cada mensagem continua relevante para a reserva específica.

Processamento de usuários e lotes

As etapas de Contexto processam usuários em lotes para otimizar a performance. 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 em sequência.

Isso significa que:

Exemplo: Se 3.500 usuários entrarem 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 em sequência, então um lote de 1.000 usuários leva cerca de 10,8 minutos (650 segundos; 1.000 × 650 ms).
  • Os lotes terminam em momentos diferentes, então os usuários vão passando para a próxima etapa à medida que o lote deles é concluído.
  • Os primeiros usuários podem chegar à próxima etapa vários minutos antes dos últimos, 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 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 precisa de um nome exclusivo (somente letras, números e sublinhados, com até 100 caracteres).
  • O tamanho total de todas as variáveis em uma etapa não pode ultrapassar 50 KB.
  • As variáveis passadas por disparos via API compartilham o mesmo namespace das variáveis criadas em etapas de Contexto. Então, se você redefinir uma variável em uma etapa de Contexto, ela substitui o valor da API.

Para mais detalhes e usos avançados, consulte a referência de variáveis de contexto.

Criação de uma etapa de Contexto

Etapa 1: Adicionar uma etapa

Adicione uma etapa ao seu Canvas e arraste e solte o componente da barra lateral. Você também pode selecionar o botão de adição e escolher Contexto.

Etapa 2: Definir as variáveis

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 Adicionar personalização para criar um snippet Liquid a partir de atributos existentes.
  4. Selecione Prévia para verificar o valor da sua variável de contexto.
  5. (Opcional) Para adicionar mais variáveis, selecione Adicionar variável de contexto e repita as etapas 1 a 4.
  6. Quando terminar, selecione Concluído.

Agora você pode usar sua variável de contexto em qualquer lugar que aceite Liquid, como nas etapas de Mensagem e de Atualização de usuário, selecionando Adicionar personalização. 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 do editor da etapa. Para ver o passo a passo completo, consulte a referência de variáveis de contexto.

Filtros de variáveis de contexto

Você pode criar filtros usando variáveis de contexto nas etapas de Jornadas de 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 etapa de Jornadas de público ou de Divisão de decisão. A etapa de agente armazena a 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, digite o caminho no campo Nome da variável de contexto 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 estiver aninhada em intent_agent).

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

Prévia das jornadas de usuários

Recomendamos testar e fazer a prévia das 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.

Fique atento aos cenários comuns que geram variáveis de contexto inválidas. Ao fazer a prévia da jornada do usuário, você pode ver os resultados das etapas de postergação personalizadas que usam variáveis de contexto. Também pode ver as comparações nas etapas de público ou 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 seu Canvas também não vão funcionar corretamente. Por exemplo, se você criar uma etapa de contexto para atribuir aos usuários um horário de agendamento e definir o valor desse horário como uma data passada, o e-mail de lembrete na sua etapa de mensagem não será enviado.

Conversão de strings do Connected Content em JSON

Quando você faz uma chamada de Connected Content em uma etapa de Contexto, o JSON retornado pela chamada é avaliado como um tipo de dado string, para garantir consistência e evitar erros. Se quiser converter essa string em JSON, use as_json_string. Por exemplo:

{% 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 retorna, no momento da execução, um valor que não corresponde ao tipo de dados ou que está vazio (nulo).
  • A expressão Liquid chama {% abort_message() %}.

Por exemplo, se o tipo de dados da variável de contexto for Número, mas a expressão Liquid retornar uma string, a variável é inválida.

Nesses casos:

  • O usuário avança para a próxima etapa.
  • A análise de dados da etapa do Canvas contabiliza isso como Não atualizado.

Ao solucionar problemas, monitore a métrica Não atualizado para verificar se a 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 talvez não se qualifiquem para as etapas seguintes.

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

Uma variável de contexto também pode ser ignorada de propósito com abort_message. Veja Usar abort_message em uma variável de contexto.

Usar abort_message em uma variável de contexto

Você pode usar a Liquid tag abort_message no valor de uma variável de contexto para ignorar essa variável para alguns usuários. Em uma etapa de Contexto, o abort_message afeta apenas a variável em que está. Ele não interrompe a etapa nem faz o usuário sair 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 da etapa continuam sendo avaliadas e definidas.
  • As 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 contabiliza a variável como Não atualizado.

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

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

Ao visualizar a prévia das jornadas do usuário, uma variável ignorada aparece como “variable_name não foi atualizada porque a lógica Liquid disparou uma interrupção”.

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

Atrasos no envio com Connected Content

Todos os usuários de um lote são processados antes que qualquer usuário avance. Depois que o processamento do lote termina, os usuários bem-sucedidos passam para a próxima etapa, enquanto os usuários com falha passam por novas tentativas separadamente. Ou seja, os usuários bem-sucedidos não esperam as novas tentativas terem sucesso para avançar.

Comportamento de novas tentativas

As chamadas de Connected Content em um Canvas só fazem novas tentativas quando a chamada inclui :retry.

  • Etapas de Contexto e de Atualização do Usuário: A Braze tenta novamente 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 continua usando o pipeline de envio de mensagens. Os destinatários ficam aguardando na fila de envio enquanto a Braze tenta novamente a chamada até cinco vezes. Se todas as tentativas falharem, a mensagem é interrompida e o usuário avança para a próxima etapa.

Nas etapas de Contexto e de Atualização do Usuário, alguns erros de etapa que permitem nova tentativa, como uma falha ao buscar um 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 faça o usuário sair do Canvas.

Para saber mais sobre a tag :retry, consulte Novas tentativas do 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
  • O uso ou não de Connected Content (e o tempo de resposta dele)
  • 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 esses limites naturalmente. No entanto, vários lotes são processados em paralelo, então confirme que o seu endpoint consegue lidar com solicitações simultâneas de vários lotes.

Consistência de fuso horário

Em espaços de trabalho com Canvas Context, todas as propriedades de evento de data e hora padrão em Canvas baseados em ação ficam em UTC. Isso vale mesmo que o Canvas não use uma etapa de Contexto.

Perguntas frequentes

Como o Contexto do Canvas afeta os registros de data e hora?

Para espaços de trabalho com Contexto do Canvas:

  • Todos os registros de data e hora com um tipo datetime vindos de propriedades do 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 usar ou não uma etapa de Contexto.

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.

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

Não.

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

Sim, ela 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 time_zone do Liquid para que os registros de data e hora sejam representados no fuso horário desejado.

Veja um exemplo de como fazer isso:

Liquid na etapa de Mensagem Resultado Essa é a forma correta de representar fusos horários no Liquid?
{{canvas_entry_properties.${timestamp_property}}} 2025-08-05T08:15:30:250-0800 Não
{{canvas_entry_properties.${timestamp_property} | date: "%Y-%m-%d %l:%M %p"}} 2025-08-05 4:15pm Não
{{canvas_entry_properties.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}} 2025-08-05 8:15am Sim

Qual é um exemplo prático de como o novo comportamento dos registros de data e hora pode afetar minhas mensagens?

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

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:

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

Como nenhum fuso horário foi especificado com Liquid, o registro de data e hora aqui está em UTC.

Para especificar um fuso horário de forma clara, podemos usar filtros time_zone do Liquid assim:

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:

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

Como o fuso horário America/Los Angeles foi especificado com Liquid, o registro de data e 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 do Liquid:

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

Qual é a diferença entre variáveis de contexto e 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 de Liquid.

As variáveis podem fazer referência 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. Então, você poderia configurar as seguintes variáveis de contexto:

Variável de contexto Valor Descrição
favorite_cuisine {{custom_attribute.${Favorite Cuisine}}} O tipo de culinária favorito de um usuário.
promo_code EATFRESH O código de desconto disponível para um usuário.
personalized_message "Enjoy a discount of" {{context.${promo_code}}} "on delivery from your favorite" {{context.${favorite_cuisine}}} restaurants!" Uma mensagem personalizada que combina as variáveis anteriores. Em uma etapa de Mensagem, você poderia usar o snippet de Liquid {{context.${personalized_message}}} para referenciar a variável de contexto e entregar uma mensagem personalizada a cada usuário. Você também poderia usar uma etapa de Contexto para salvar o valor do código promocional e usá-lo como modelo em outras etapas ao longo de um Canvas.

Isso também se aplica a várias 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. Mais adiante, uma etapa de Contexto atualiza a variável de contexto, alterando o valor de JobInfo para job_description.
  4. Todas as etapas seguintes que referenciam JobInfo passam a usar o valor atualizado job_description.

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

New Stuff!