Solução de problemas do Canvas
Use esta página para diagnosticar problemas de entrada, envio e análise de dados do Canvas. Para definições e aprofundamentos, consulte as Perguntas frequentes do Canvas.
Após o lançamento, comece pela Fase 5: Monitoramento pós-lançamento no checklist de QA do Canvas para identificar padrões comuns na primeira hora (picos de entregabilidade, muitas entradas com poucos envios, público vazio e queda em etapas). Retorne aqui quando precisar de um caminho de investigação mais aprofundado.
Os registros do Histórico de mensagens e do Diagnóstico de mensagens ficam disponíveis por até 30 dias a partir do evento. Entre em contato com o suporte da Braze dentro desse período se precisar de ajuda para investigar um incidente específico.
Comece aqui: identifique seu sintoma
| Sintoma | Acesse |
|---|---|
| Um usuário não entrou no Canvas | O usuário não entrou no Canvas |
| Um usuário entrou, mas não recebeu uma mensagem ou etapa | O usuário não recebeu uma mensagem ou etapa do Canvas |
| Ninguém ou menos usuários entraram do que o esperado | Entradas baixas ou zero no Canvas |
| Envios ou entregas estão abaixo do público estimado | Menos envios do que o esperado |
| A análise de dados do Canvas parece errada (grupo de controle, conversões, zero envios) | Divergências na análise de dados do Canvas |
| A análise de dados mostra muito mais envios do que entradas, ou mais saídas do que entradas | A filtragem por intervalo de datas pode mostrar números inesperados |
| O Canvas não salva ou o editor congela | Problemas com o editor e ao salvar |
| Não é possível excluir uma variante do Canvas | Não é possível excluir uma variante do Canvas por causa de um Segment arquivado |
| Parei o Canvas, mas as mensagens ainda foram enviadas | Comportamento do Canvas interrompido |
| Erro “Too many Canvas branches” ao lançar | Erro “Too many Canvas branches” |
Caminho de investigação padrão
Use este fluxo de trabalho para investigar um usuário específico ou um problema de envio em lote. Comece pela etapa 1 para cada incidente.
- Confirme que o Canvas está ativo (não é rascunho, parado ou arquivado).
- Confirme que o cronograma de entrada (janela agendada, fuso horário, disparo baseado em ação ou entrada disparada por API) corresponde ao momento em que você espera que os usuários entrem.
- Verifique o registro de envio de mensagens de um usuário acessando Público > Pesquisar usuários, abrindo o perfil e selecionando Histórico de mensagens (últimos 30 dias).
- Se não houver registro para o horário de envio esperado, o problema está na entrada, não na mensagem. Acesse O usuário não entrou no Canvas.
- Verifique o Changelog do Canvas e os changelogs de quaisquer Segments usados no direcionamento. Confirme que o público, as etapas ou as configurações de envio não foram alterados durante o incidente.
- Verifique os resultados agregados na página de análise de dados do Canvas abrindo Messaging Observability e revisando os motivos de interrupção e descarte.
- Se você identificar um resultado que não reconhece, consulte Resultados de interrupção na documentação de Messaging Observability.
- Se uma etapa mostrar zero entradas (não zero envios), verifique o tipo de etapa anterior (Jornadas de ação, Postergação, Jornadas do público ou Divisão de decisão).
- Se você ainda estiver bloqueado, entre em contato com o suporte da Braze dentro de 30 dias com o ID do Canvas, os IDs dos usuários afetados, carimbos de data/hora (com fuso horário) e capturas de tela do Histórico de mensagens ou do Messaging Observability.
Antes do lançamento, use Enviar Canvas de teste e Prévia de jornadas de usuário para validar sua configuração.
O usuário não entrou no Canvas
Sintoma: Um usuário não entrou no Canvas quando você esperava, ou menos usuários entraram do que os eventos-gatilho sugerem.
Os usuários devem corresponder ao Público-Alvo antes de a Braze avaliar o gatilho de entrada (exceto para gatilhos de mudança de atributo). Um gatilho sozinho não garante a entrada se o usuário não estava no público no momento da avaliação.
Reelegibilidade e reentrada são controles separados em Seleção de controles de entrada:
- Reelegibilidade: Determina se um usuário pode entrar novamente no Canvas após sair (janela de tempo e configuração Permitir que os usuários reentrem no Canvas).
- Reentrada: Determina se um usuário que está atualmente dentro do Canvas pode entrar em uma jornada simultânea.
Um usuário pode ser reelegível, mas estar bloqueado porque ainda está no Canvas, ou pode ter saído, mas ainda estar fora da janela de reelegibilidade. Verifique ambas as configurações quando um usuário não reentra em um Canvas.
Verifique o seguinte:
- Cronograma de entrada e fuso horário: Confirme se o Canvas estava ativo e se o usuário realizou o gatilho durante a janela de entrada.
- Público-alvo no momento da avaliação: Revise os changelogs de Segments e filtros. A Pesquisa de Usuário pode apresentar um falso positivo para alguns tipos de filtros (por exemplo, atributos de data formatados como string).
- Limites de entrada: Os limites máximos de entradas ou limites de público podem ter sido atingidos.
- Grupo de controle global: Os usuários no grupo de controle global não entram em Canvas de envio de mensagens.
- Grupo de controle do Canvas: Os usuários atribuídos ao grupo de controle do Canvas na entrada não recebem mensagens de variante. A atribuição de variante acontece na entrada, não por filtros de Segment. Consulte Divergências na análise de dados do Canvas.
- Critérios de saída: O usuário pode ter correspondido aos critérios de saída antes ou durante a entrada. Se a entrada e a saída usam o mesmo evento, consulte Correspondência de critérios de entrada e saída.
- Entrada disparada por API: Confirme se o usuário foi adicionado com o endpoint
/canvas/trigger/send. Você pode criar um Segment com um filtro de entrada do Canvas e exportar os usuários com/users/export/segment.
A contagem de eventos-gatilho é maior do que as entradas no Canvas
Sintoma: O volume de eventos-gatilho é maior do que o número de entradas no Canvas.
A Braze faz a deduplicação de múltiplas tentativas de entrada que ocorrem no mesmo instante, então você pode ver menos entradas no Canvas do que eventos-gatilho. Para testar múltiplas entradas, espaçe os eventos-gatilho com pelo menos um segundo de intervalo.
Se um usuário realiza o mesmo gatilho várias vezes dentro de um segundo, a Braze processa apenas uma entrada. Verifique o Messaging Observability para resultados como User not re-eligible quando regras de reentrada ou reelegibilidade se aplicam.
Horário de verão e Canvas agendados diariamente
Em dias de transição do horário de verão, Canvas agendados diariamente podem ser executados até uma hora antes ou depois do horário habitual. Se seus critérios de entrada dependem de atributos personalizados ou eventos com timestamps que estão dentro de uma hora do horário de entrada agendado, os usuários podem não se qualificar no dia da transição porque o atributo ou evento ainda não foi registrado.
Por exemplo, suponha que os usuários normalmente recebem uma atualização de atributo personalizado às 15h no fuso horário do seu Canvas e seu Canvas é executado diariamente às 15h30 nesse mesmo fuso horário. Em um dia de adiantamento do horário de verão, o Canvas pode avaliar os usuários até uma hora antes do habitual em relação à atualização do atributo — antes que o atributo tenha sido registrado. Se a reelegibilidade estiver desativada, os usuários que entraram em dias anteriores não poderão reentrar, resultando em zero entradas naquele dia.
Para evitar isso, garanta que as atualizações de atributos personalizados ou eventos ocorram mais de uma hora antes do horário de entrada agendado do Canvas.
O usuário não recebeu uma mensagem ou etapa do Canvas
Sintoma: Um usuário entrou no Canvas, mas não recebeu a mensagem ou etapa esperada.
Verifique o Histórico de mensagens do usuário para a etapa do Canvas e o timestamp. Se não houver registro, retorne a O usuário não entrou no Canvas.
Em seguida, verifique o seguinte por tipo de disparador ou etapa:
- Disparadores de evento personalizado ou compra: Confirme se o evento aparece em Analytics > Custom Events Report (ou Revenue para compras). Compare o timestamp do evento com o momento em que o Canvas entrou em operação e com qualquer postergação agendada na etapa.
- Entrada disparada por API: Confirme a entrada com um filtro de Segment do Canvas e exportação, conforme descrito em O usuário não entrou no Canvas.
- Jornadas de ação ou disparadores de etapa de mensagem: Confirme se o usuário realizou o evento pré-requisito e se as propriedades do evento estão disponíveis na etapa.
- Etapas de mensagem no app: As mensagens no app são enviadas no próximo início de sessão após o usuário entrar na etapa, e somente a partir de eventos do SDK (não da REST API). Consulte Quando as mensagens no app no Canvas são enviadas? no FAQ do Canvas.
- Grupo de controle do Canvas: Verifique se o usuário não foi atribuído ao grupo de controle do Canvas na entrada.
- Elegibilidade de canal e configurações de envio: Confirme o status de inscrição, o estado de push ativado e as Configurações de envio por etapa (por exemplo, Subscription Settings definido apenas para usuários com opt-in). Não adicione filtros de canal único ao Target Audience em Canvas multicanal.
- Validações de entrega: Se você ativou Validate audience at message send em uma etapa de mensagem, os usuários que não correspondem mais aos filtros no momento do envio não recebem a mensagem. Consulte Validações de entrega.
- Horário de silêncio, Intelligent Timing, limites de frequência e limites de taxa: Esses recursos podem adiar, suprimir ou interromper envios. Os usuários podem permanecer no Canvas após uma interrupção por horário de silêncio.
- Condições de corrida: Se o usuário disparou várias ações ao mesmo tempo, consulte Condições de corrida.
Quando uma etapa de mensagem do Canvas interrompe um envio, o usuário ainda avança para a próxima etapa. O Canvas avança após a interrupção para que etapas posteriores de postergação e jornadas de ação não fiquem permanentemente bloqueadas. Consulte Como os usuários avançam e Resultados de interrupção.
Para o timing de envio de mensagens no app após postergações ou ramificações, consulte o FAQ do Canvas. Para o avanço em etapas de mensagem com divisão de decisão ou jornadas de ação, consulte Revisar etapas de mensagem para avanço do usuário no checklist de QA do Canvas.
Se o seu Canvas baseado em ação está enviando mensagens antes do esperado, verifique se o timestamp do evento personalizado usa a hora atual, e não uma hora retroativa. A Braze avalia postergações a partir do timestamp enviado com o evento. Consulte Entrega baseada em ação.
Entradas baixas ou zeradas no Canvas
Sintoma: Nenhum usuário ou menos usuários do que o esperado entraram no Canvas.
Comece com o checklist de QA do Canvas e depois confirme:
- O Canvas está ativo e o horário atual está dentro da janela de entrada agendada.
- As configurações de entrada (reelegibilidade, número máximo de entradas e limites de entrada) permitem que os usuários esperados entrem.
- O público-alvo e os filtros de Segment ainda correspondem aos usuários esperados após o lançamento.
- As porcentagens do grupo de controle global e do Canvas mostram qual parcela de usuários entra em cada jornada versus recebe mensagens.
- Limites de frequência do espaço de trabalho ou filas de entrada podem adicionar atrasos entre o momento em que os usuários se qualificam e o momento em que entram ou avançam para uma etapa.
Para um único usuário, siga o caminho de investigação padrão. Para entradas zeradas relacionadas ao horário de verão, consulte a seção recolhível em O usuário não entrou no Canvas.
Envios menores do que o esperado
Sintoma: Os envios ou entregas são menores do que o público estimado em uma etapa do Canvas.
As causas comuns incluem reavaliação do público no momento do envio, elegibilidade do canal, grupos de controle, horário de silêncio, Intelligent Timing, limites de frequência e comportamento de entrega de mensagens no app (zero Envios com impressões é esperado para mensagens no app).
Se uma etapa de Mensagem mostra que muitos usuários entraram, mas poucos envios foram feitos, verifique se o Liquid abort_message() cancelou o envio. Para saber como confirmar essas interrupções, atributos ausentes e envios de teste, consulte Solução de problemas de altas taxas de interrupção.
Para uma lista detalhada, consulte Por que os envios são menores do que o tamanho estimado do público? no FAQ do Canvas e Por que os envios são menores do que o tamanho estimado do público? para Campaigns.
Use o histórico de mensagens para ver os motivos de interrupção e descarte no nível da etapa.
Divergências na análise de dados do Canvas
Sintoma: A análise de dados do Canvas parece incorreta (divisões de grupo de controle, conversões ou zero envios).
A atribuição ao grupo de controle e à variante ocorre na entrada do Canvas, com base nas porcentagens definidas no construtor — não por meio de filtros de Segment. Usuários que não podem receber um canal específico ainda podem entrar em uma variante; use as Configurações de envio por etapa para limitar quem recebe cada tipo de mensagem, em vez de restringir o Público-alvo com filtros de canal.
Diferencie o grupo de controle do Canvas do grupo de controle global. Para definições de filtros, consulte Qual é a diferença entre “Has not entered Canvas variation” e “Is not in Canvas control group”? nas perguntas frequentes do Canvas.
Por que os envios de uma variante podem ser menores do que a porcentagem da variante
Imagine o seguinte cenário:
- Um Canvas tem uma única variante e um grupo de controle.
- A primeira etapa da variante é uma notificação por push.
- 90% dos usuários foram selecionados para entrar na variante e 10% para entrar no grupo de controle.
Nesse cenário, 90% dos usuários que entram no Canvas entram na variante.
Ao verificar o Segment de usuários ativos, você verá que, embora ele contenha 29,8 mil usuários, apenas 64% deles têm push ativado:
Isso significa que, apesar de você ter especificado 90% dos usuários para entrar na variante, nem todos podem receber uma notificação por push. Usuários que não podem receber push ainda entram na variante — a contagem de envios reflete a elegibilidade do canal na etapa, não a atribuição da variante na entrada.
O filtro de intervalo de datas pode exibir números inesperados
Sintoma: A análise de dados do Canvas ou da etapa mostra números inesperados ou improváveis, como muito mais envios do que entradas, ou mais usuários saindo de uma etapa do que entraram.
Isso pode acontecer quando você usa o filtro de calendário de intervalo de datas na parte superior da página de análise de dados do Canvas. Se você selecionar um intervalo de datas que exclui algumas ações dos usuários, as métricas exibidas podem mostrar apenas parte da jornada de cada usuário.
Por exemplo:
- Você pode ver 100 entradas com 8.000 envios se o intervalo de datas começar depois que a maioria dos usuários entrou, mas incluir o período em que receberam mensagens.
- Você pode ver mais usuários avançando para a próxima etapa do que os que entraram na etapa anterior, caso o intervalo capture apenas as saídas, mas não as entradas anteriores.
Para resolver isso, ajuste o intervalo de datas para incluir todas as datas desde o lançamento do Canvas até o momento atual, ou selecione um intervalo que cubra todo o período relevante para as métricas que você precisa.
Para definições de taxa de conversão e análise de dados por etapa, consulte Análise de dados e conversões nas perguntas frequentes do Canvas.
Problemas com o editor e salvamento
Sintoma: O editor de Canvas não carrega, trava ou não salva suas alterações.
| Sintoma | Causa mais provável |
|---|---|
| O botão Salvar gira indefinidamente sem erro | Filtro de atributo personalizado vazio ou incompleto no público do Canvas ou em um filtro de etapa — remova o filtro ou selecione um atributo válido |
| Erro “Request Timed Out” durante a edição | Interferência de extensão do navegador, bloqueadores de anúncios ou sessão expirada — tente uma janela anônima ou outro navegador |
| Não é possível salvar após arquivar uma variante | Uma variante arquivada ainda é referenciada em etapas posteriores; revise as conexões entre etapas e restaure ou substitua a variante |
Se você tiver o mesmo Canvas aberto em várias abas do navegador, salvar em uma aba pode sobrescrever as alterações feitas em outra aba desatualizada. Essa condição de corrida pode levar à remoção de filtros de público ou à aplicação de alterações indesejadas. Para evitar perda de dados, feche quaisquer abas duplicadas antes de editar e salvar um Canvas.
Se o editor travar em um Canvas grande ou complexo, tente o seguinte:
- Limpe o cache e os cookies do navegador e recarregue a página. Bloqueadores de anúncios corporativos ou extensões do navegador podem interferir na plataforma da Braze.
- Use os controles de zoom do Canvas para reduzir a visualização para 25% ou 10%, diminuindo a quantidade de interface que o navegador precisa renderizar.
- Tente um navegador de internet diferente.
Se o Canvas não carregar e não avançar, é possível que uma versão anterior não tenha sido salva corretamente e contenha etapas inválidas. Duplique o Canvas pelo dashboard. Se o problema persistir, abra um ticket de suporte.
Para tickets de suporte sobre “Request Timed Out”, inclua uma gravação de tela, data/hora e fuso horário, navegador e versão, etapas para reproduzir o problema e, opcionalmente, um log HAR das ferramentas de desenvolvedor do navegador. Consulte O que devo incluir ao enviar um ticket de suporte para um erro “Request Timed Out”? nas Perguntas frequentes sobre Canvas.
Não é possível excluir uma variante de Canvas por causa de um Segment arquivado
Se a Braze bloquear a exclusão de uma variante de Canvas porque um filtro de Segment ainda faz referência a essa variante, abra o Segment que usa a referência — incluindo segmentos arquivados — e remova a variante dos filtros. Depois de salvar o Segment, volte ao Canvas e tente excluir a variante novamente.
Para descobrir quais segmentos fazem referência a um Canvas, abra o Canvas e revise os filtros de público, ou verifique a seção Uso em envio de mensagens de cada Segment para identificar Canvas vinculados.
Comportamento de Canvas parado
Sintoma: Você parou o Canvas, mas os usuários ainda receberam mensagens.
Quando você para um Canvas, os usuários não podem entrar e nenhuma mensagem adicional é enviada pelo fluxo do Canvas. Envios de e-mail já encaminhados ao seu provedor de serviços de e-mail não podem ser recuperados.
Usuários aguardando em uma etapa de postergação ou jornadas de ação não são automaticamente removidos da jornada quando você para o Canvas. Se você reativar o Canvas antes do horário de envio agendado, eles ainda poderão receber as etapas pendentes.
Para mais detalhes, consulte O que acontece quando você para um Canvas? nas perguntas frequentes sobre Canvas.
Erro “Too many Canvas branches”
Sintoma: Você vê o erro “Too many Canvas branches” ao lançar um Canvas agendado.
Esse erro aparece quando a combinação de ramificações de etapas e o tamanho do público de entrada pode gerar problemas de desempenho no cluster que impedem o envio de mensagens. A Braze exibe essa mensagem quando você lança um Canvas com entrada agendada — ela não aparece quando você salva um rascunho.
Para resolver:
- Reduza as ramificações de etapas no Canvas.
- Reduza o tamanho do público de entrada.
- Use jornadas do público para consolidar ramificações em vez de muitas jornadas paralelas.
- Se o seu Canvas usa o editor original, clone-o para o Canvas Flow e reconstrua com componentes do Canvas.
Se você ainda precisar lançar o Canvas sem alterações e não puder migrar para o Canvas Flow, entre em contato com o suporte da Braze.
Quando entrar em contato com o suporte
Entre em contato com o suporte da Braze em até 30 dias após o problema, caso tenha concluído o caminho de investigação padrão e ainda precise de ajuda.
Inclua:
- ID do Canvas e IDs dos usuários afetados (ID externo ou ID da Braze)
- Timestamps com fuso horário
- Capturas de tela ou exportações do histórico de mensagens ou Messaging Observability
- Para erros “Request Timed Out” no editor, os detalhes listados em Problemas com o editor e salvamento