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 do que o esperado entraram | Poucas ou zero entradas no Canvas |
| Os envios ou entregas são menores do que o público estimado | Menos envios do que o esperado |
| A análise de dados do Canvas parece incorreta (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 de Canvas parado |
| 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 agregado. Comece pela etapa 1 para cada incidente.
- Confirme se o Canvas está ativo (não rascunho, parado ou arquivado).
- Confirme se o cronograma de entrada (janela agendada, fuso horário, gatilho 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 Audience > Search users, abrindo o perfil e selecionando Messaging History (ú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 se 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 supressões e falhas.
- Se você vir um resultado que não reconhece, consulte Suppressions e Failures na documentação do Messaging Observability.
- Se uma etapa mostrar zero entradas (não zero envios), verifique o tipo da etapa anterior (jornadas de ação, postergação, jornadas do público ou divisão de decisão).
- Se ainda estiver sem solução, entre em contato com o suporte da Braze em até 30 dias com o ID do Canvas, IDs dos usuários afetados, carimbos de data/hora (com fuso horário) e capturas de tela do Messaging History ou do Messaging Observability.
Antes do lançamento, use Enviar Canvas de teste e Prévia de jornadas do 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 que a Braze avalie o gatilho de entrada (exceto para gatilhos de alteração de atributo). Um gatilho por si só não garante a entrada se o usuário não estava no público no momento da avaliação.
A reelegibilidade e a reentrada são controles separados em Seleção de controles de entrada:
- Reelegibilidade: Determina se um usuário pode entrar no Canvas novamente 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 conseguir reentrar em um Canvas.
Verifique o seguinte:
- Cronograma de entrada e fuso horário: Confirme que o Canvas estava ativo e que 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. O User Lookup pode mostrar um falso positivo para alguns tipos de filtros (por exemplo, atributos de data formatados como string).
- Limites de entrada: Os limites máximos de entrada ou limites de público podem ter sido atingidos.
- Grupo de controle global: Usuários no grupo de controle global não entram em Canvas de envio de mensagens.
- Grupo de controle do Canvas: Usuários atribuídos ao grupo de controle do Canvas na entrada não recebem mensagens de variantes. A atribuição de variante acontece na entrada, não por meio de 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 que o usuário foi adicionado com o endpoint
/canvas/trigger/send. Você pode criar um Segment com um filtro de entrada no Canvas e exportar 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 a contagem 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 em 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 de 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 ocorrem dentro de uma hora do horário de entrada agendado, os usuários podem ainda não se qualificar no dia da mudança de horário 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 de horário de verão, o Canvas pode avaliar os usuários até uma hora antes do habitual em relação àquela atualização de atributo — antes que o atributo tenha sido registrado. Se a reelegibilidade estiver desativada, os usuários que entraram em dias anteriores não podem 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 carimbo de data/hora. Se não houver registro, volte para O usuário não entrou no Canvas.
Em seguida, verifique o seguinte de acordo com o tipo de gatilho ou etapa:
- Gatilhos de evento personalizado ou compra: Confirme se o evento aparece em Analytics > Custom Events Report (ou Revenue para compras). Compare o carimbo de data/hora 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 gatilhos da 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 apenas a partir de eventos do SDK (não pela 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 multicanais.
- 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 na interrupção para que as etapas posteriores de postergação e jornadas de ação não fiquem permanentemente bloqueadas. Consulte Como os usuários avançam, Supressões e Falhas em Messaging Observability.
Para o tempo de envio de mensagens no app após postergações ou ramificações, consulte o FAQ do Canvas. Para o avanço na etapa 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 envia mensagens antes do esperado, verifique se o carimbo de data/hora do evento personalizado usa a hora atual, e não uma hora retroativa. A Braze avalia as postergações a partir do carimbo de data/hora enviado com o evento. Consulte Entrega baseada em ação.
Entradas baixas ou zeradas no Canvas
Sintoma: Ninguém ou menos usuários do que o esperado entraram no Canvas.
Comece com a checklist de QA do Canvas e depois confirme:
- O Canvas está ativo e o horário atual está dentro da janela de entrada programada.
- As configurações de entrada (reelegibilidade, 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.
- Os percentuais do grupo de controle global e do Canvas mostram qual parcela de usuários entra em cada jornada versus recebe mensagens.
- Os limites de frequência do espaço de trabalho ou as filas de entrada devem 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? nas perguntas frequentes sobre Canvas e Por que os envios são menores do que o tamanho estimado do público? para Campaigns.
Use o Messaging Observability para ver supressões e falhas 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 do grupo de controle, conversões ou zero envios).
A atribuição do grupo de controle e da variante acontece na entrada do Canvas com base nas porcentagens definidas no criador, 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 são direcionados para a variante.
Ao analisar o Segment de usuários ativos, você verá que, embora ele contenha 29,8 mil usuários, apenas 64% deles estão com push ativado:
Isso significa que, embora você tenha especificado que 90% dos usuários entrem 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 mostrar 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 no topo da página de análise de dados do Canvas. Se você selecionar um intervalo 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 após a maioria dos usuários ter entrado, mas incluir o período em que eles receberam mensagens.
- Você pode ver mais usuários avançando para a próxima etapa do que os que entraram na etapa anterior, se o intervalo capturar 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 presente, ou selecione um intervalo que cubra todo o período relevante para as métricas necessárias.
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 no editor e ao salvar
Sintoma: O editor do Canvas não carrega, congela ou não salva suas alterações.
| Sintoma | Causa mais provável |
|---|---|
| O botão de 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” ao editar | 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 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 congelar 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 progredir, uma versão anterior não foi salva corretamente e pode conter etapas inválidas. Duplique o Canvas a partir do 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 do 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 removidos automaticamente da jornada quando você para o Canvas. Se você reativar o Canvas antes que o horário de envio agendado passe, 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ção de etapas e tamanho do público de entrada pode criar 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 a ramificação de etapas no Canvas.
- Reduza o tamanho do público de entrada.
- Use jornadas do público para consolidar ramificações em vez de usar muitas jornadas paralelas.
- Se o seu Canvas usa o editor original, clone-o para o Canvas Flow e reconstrua com componentes do Canvas.
Se ainda assim você 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 você 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)
- Carimbos de data/hora com fuso horário
- Capturas de tela ou exportações do histórico de mensagens ou do Messaging Observability
- Para erros de “Request Timed Out” no editor, os detalhes listados em Problemas no editor e ao salvar