Solução de problemas de push

Use esta página para solucionar problemas de entrega de push, comportamento ao clicar e credenciais. Para configuração específica do SDK, consulte Solução de problemas de notificações por push para o SDK da Braze. Para códigos de erro, consulte Mensagens de erro comuns de push.

Comece aqui: identifique seu sintoma

Sintoma	Acesse
O usuário não recebeu uma notificação por push	Notificações por push ausentes
As notificações por push chegam com atraso	Notificações por push atrasadas
Os envios de push estão mais lentos do que o esperado	As notificações por push estão sendo enviadas mais lentamente do que o esperado
Erro MismatchSenderID (Android)	Erro: MismatchSenderID
Tocar em uma notificação por push não abre o app	Clicar em uma notificação por push não abre o app
Links de push abrem no app em vez do navegador	Cliques em push abrem inesperadamente no app
Problemas de permissão ou entrega de web push	As notificações web push não estão funcionando como esperado
Precisa migrar de .p12 para .p8 (iOS)	Migrar para uma chave de autenticação .p8
Código de erro de push específico nos logs	Mensagens de erro de push

Caminho de investigação padrão

Use este fluxo quando um usuário ou dispositivo de teste não recebeu uma notificação por push. Comece pela etapa 1.

1. Confirme se o usuário está inscrito ou optou por receber push e se possui um token por push válido na guia Engajamento do perfil.
2. Confirme se o usuário está no público-alvo da Campaign ou do Canvas no momento do envio (os Segments são atualizados em tempo real).
3. Verifique os limites de frequência globais, os limites de frequência de envio e a atribuição ao grupo de controle da Campaign ou do Canvas.
4. Confirme se você está usando o tipo correto de push para o dispositivo (por exemplo, Android, iOS ou Kindle).
5. Para testes internos, confirme se o testador está conectado ao app correto no dispositivo.
6. Se a entrega ainda falhar, consulte Mensagens comuns de erro de push ou entre em contato com o suporte da Braze informando o ID da Campaign ou do Canvas, o ID do usuário e o registro de data e hora com fuso horário.

Notificações por push ausentes

Sintoma: Um usuário não recebeu uma notificação por push esperada.

Se as notificações por push não estão chegando como esperado, verifique os seguintes itens:

• Status da inscrição para push
• Segment
• Limites de notificações por push
• Limites de frequência
• Status do grupo de controle
• Token por push válido
• Tipo de notificação por push
• App atual

Status da inscrição para push

Pushes só podem ser enviados para usuários inscritos ou que optaram por receber. No Perfil de usuário, abra a guia Engajamento e confirme que você está ativamente registrado para push no espaço de trabalho que está testando. Se você estiver registrado em vários apps, eles serão listados em Push Registered For:

Você também pode exportar perfis de usuário usando os endpoints de exportação da Braze:

• Usuários por identificador
• Usuários por segmento

Ambos os endpoints retornam um objeto de token por push que inclui informações de ativação de push por dispositivo.

Segment

Confirme que você faz parte do segmento que está sendo direcionado (se for uma campanha ativa e não um teste). No Perfil de usuário, você pode ver em quais segmentos o usuário está atualmente incluído. A associação ao segmento é atualizada em tempo real.

Você também pode confirmar que o usuário faz parte do segmento usando a Pesquisa de usuário ao criar um segmento. A Pesquisa de usuário aceita apenas external_id ou braze_id — não endereços de e-mail ou números de telefone. Para pesquisar por e-mail, telefone, token por push ou alias de usuário, consulte Pesquisar usuários.

Limites de notificações por push

Verifique os limites de frequência globais. É possível que você não tenha recebido a notificação por push porque seu espaço de trabalho possui limite de frequência global ativo e você já atingiu o limite de notificações por push para o período especificado.

Na página Analytics da Campaign, verifique se há um banner de limite de frequência mostrando aproximadamente quantos usuários não receberam a Campaign nos últimos 30 dias. Para investigar envios individuais, use o dashboard de Diagnóstico de mensagens e filtre por Frequency capped. Para revisar ou alterar as regras, consulte limite de frequência global.

Limites de frequência

Se você tiver um limite de frequência definido para sua Campaign ou Canvas, pode estar deixando de receber mensagens por ter excedido esse limite. Para saber mais, consulte Limite de frequência.

Status do grupo de controle

Se for uma Campaign de canal único ou um Canvas com grupo de controle, é possível que você esteja no grupo de controle.

1. Verifique a distribuição de variantes para ver se há um grupo de controle.
2. Se houver, crie um segmento filtrando por no grupo de controle da Campaign e depois exporte o segmento e verifique se o ID do seu usuário está nessa lista.

Token por push válido

Um token por push é um identificador que os remetentes usam para direcionar um dispositivo específico com uma notificação por push. Sem um token por push válido, a Braze não consegue enviar um push para esse dispositivo.

A Braze armazena até 20 dispositivos por perfil de usuário. Quando um 21º dispositivo é registrado, o dispositivo mais antigo é removido (primeiro a entrar, primeiro a sair, ou FIFO). Chamar changeUser() no SDK registra novamente o dispositivo atual no perfil.

Tipo de notificação por push

Use o tipo de push que corresponde ao dispositivo ou plataforma que você está direcionando. Por exemplo, use uma notificação por push Kindle para Fire TV, não uma Campaign de push para Android. Para dispositivos Android, use uma notificação por push para Android em vez de uma Campaign de push para iOS.

Para fluxos de trabalho de solução de problemas específicos por plataforma, consulte:

• Solução de problemas de notificações por push da Apple
• Solução de problemas do Firebase Cloud Messaging

App atual

Ao testar push com usuários internos, confirme que o destinatário pretendido está logado no app correto. Caso contrário, ele pode não receber o push ou pode receber um que você não esperava com base na segmentação.

Erro: MismatchSenderID

Sintoma: O push para Android falha com um erro MismatchSenderID.

MismatchSenderID indica uma falha de autenticação com o Firebase Cloud Messaging (FCM). Confirme se o ID do remetente do Firebase e a chave de API do FCM estão corretos.

Para encontrar a chave de servidor correta do Firebase e substituí-la:

1. Acesse o console do Firebase do seu app.
2. Em Project Overview, selecione Project Settings.
3. Na guia Cloud Messaging, verifique se o ID do remetente listado com as chaves de API corresponde ao que está na Braze (em Settings > App Settings > Cloud Messaging API Key).

1. Copie a Server Key em Project credentials.
2. Na Braze, acesse Settings > App Settings, selecione seu app e cole a chave do servidor no campo Cloud Messaging API Key (substituindo a chave desatualizada).
3. Selecione Save.
4. Para verificar, envie um push de teste para um dispositivo antes e depois de alterar a chave de API sem abrir o aplicativo. Isso ajuda a confirmar que os usuários continuam recebendo notificações por push sem a necessidade de gerar um novo ID de registro de push (token por push).

Cenários de solução de problemas

Notificações por push atrasadas

Sintoma: As notificações por push chegam mais tarde do que o esperado.

Suas notificações por push podem atrasar por estes motivos:

• Conexão de dados fraca no dispositivo
• Código personalizado no app que pode suprimir notificações por push da Braze
• Preferências do usuário para notificações por push nas configurações do dispositivo
• Prioridade da mensagem da notificação por push ao ser criada na Campaign ou no Canvas
• Atrasos de tráfego ou problemas com os provedores de serviço de push (FCM e APNs)

Notificações por push estão sendo enviadas mais lentamente do que o esperado

Sintoma: Os envios de push de Campaigns ou Canvas demoram mais do que o esperado para serem concluídos.

Confirme se a configuração das suas notificações por push segue estas práticas recomendadas:

• Se você está enviando para grandes públicos sem considerar o status de push ativado, isso pode resultar em uma velocidade de envio mais lenta. Em vez disso, considere enviar apenas para usuários com push ativado para reduzir o tamanho do seu público.
• Se possível, tente agendar suas Campaigns com antecedência em vez de enviá-las imediatamente.
• Se você está direcionando um número maior de usuários com notificações por push em um Canvas, pode esperar que as etapas de mensagem subsequentes no Canvas exijam tempos de processamento diferentes de uma Campaign que envia para os usuários imediatamente. Nesse caso, as Campaigns normalmente terminam o envio antes de um Canvas, pois a primeira “etapa” de um Canvas é verificar se os usuários se qualificam para a jornada de usuário específica.

Clicar em uma notificação por push não abre o app

Sintoma: Tocar em uma notificação por push não abre o app nem navega conforme configurado.

Se clicar em uma notificação por push não abre seu app, verifique o seguinte com base na sua plataforma.

Android

1. Verifique o comportamento ao clicar: Confirme que a Campaign está configurada para abrir o app ao ser clicada.
2. Verifique o tratamento de deep links: No seu arquivo braze.xml, verifique se com_braze_handle_push_deep_links_automatically está definido como true ou false.
   • Se definido como true, o SDK da Braze trata os deep links diretamente e o app deve abrir conforme esperado.
   • Se definido como false, seu app precisa de um broadcast receiver para escutar e tratar os intents de push recebido e aberto. Verifique se esse receiver está implementado corretamente.
3. Colete logs detalhados: Ative o registro detalhado, reproduza o problema e forneça os logs junto com seus arquivos braze.xml e AndroidManifest.xml ao suporte da Braze.

iOS

1. Verifique o comportamento ao clicar: Confirme que a Campaign está configurada para abrir o app ao ser clicada.
2. Verifique a integração de push: O deep linking de um push para o app é tratado automaticamente pela integração padrão de push da Braze. Confirme que a integração está implementada corretamente, incluindo qualquer tratamento de delegate personalizado.
3. Colete logs detalhados: Ative o registro detalhado, reproduza o problema e forneça os logs ao suporte da Braze.

Cliques em push abrem inesperadamente no app

Sintoma: Links em notificações por push abrem dentro do app em vez do navegador web do dispositivo.

Se você está enfrentando problemas com links em notificações por push que abrem inesperadamente no seu app em vez do navegador web, pode haver um problema com a configuração da sua Campaign ou com a implementação do SDK. Consulte as etapas a seguir para obter ajuda.

Verifique o comportamento ao clicar

Na sua Campaign ou etapa do Canvas, verifique novamente se Open web URL inside mobile app não está selecionado. Se estiver, desmarque a seleção e relance.

A interação padrão para o comportamento ao clicar “Open web URL” difere por versão do SDK. Para as versões do SDK iOS 2.29.0 e Android 2.0.0 e superiores, essa opção é selecionada por padrão e as URLs da web são abertas em uma web view dentro do app. Antes dessas versões, essa opção é desmarcada por padrão e as URLs da web abrem no navegador web padrão do dispositivo.

Se esse não for o problema, pode haver um problema com sua implementação de push.

Verifique novamente a integração de push

Se os links nas suas notificações por push estão abrindo no app inesperadamente, isso pode ser devido a problemas com a integração ou configurações de personalização das notificações por push. Siga estas etapas para solucionar:

1. Revise a implementação do delegate de push: certifique-se de que o delegate de push da Braze está implementado corretamente. Para instruções detalhadas, consulte o guia de integração de notificações por push para sua plataforma.
2. Inspecione o tratamento personalizado de links: verifique se o app inclui tratamento personalizado para todos os links https://. Configurações personalizadas podem sobrescrever comportamentos padrão. Colabore com sua equipe de desenvolvimento para revisar e ajustar essas configurações, se necessário.
3. Verifique o registro de push no iOS: para iOS, revise a etapa 1 do guia de integração de push sobre registrar notificações por push com APNs. Certifique-se de que seu objeto delegate é atribuído de forma síncrona antes que o app termine de iniciar. Essa etapa deve ser concluída no método application:didFinishLaunchingWithOptions:.
4. Teste sua integração: após fazer os ajustes, teste o comportamento das notificações por push em dispositivos iOS e Android para confirmar que o problema foi resolvido.

Deep links com o app ainda em execução em segundo plano (iOS)

Se os deep links funcionam quando o app não está em execução ou quando o link é usado diretamente, mas não quando o aplicativo já está em execução em segundo plano, o problema pode estar relacionado à forma como o app trata o link. Verifique se você está usando alguma biblioteca de terceiros que utiliza method swizzling. Recomendamos desativar o swizzling, pois ele pode causar problemas com implementações de deep link.

Migrar para uma chave de autenticação .p8

Sintoma: Você precisa migrar as credenciais de push do iOS de um certificado legado para uma chave .p8, ou a entrega de push falhou após uma alteração de credencial.

As chaves de autenticação .p8 da Apple são a abordagem obrigatória para push via APNs na Braze. Diferentemente dos tipos de arquivo de certificado legados, as chaves .p8 não expiram e suportam todos os seus apps com uma única chave, eliminando a necessidade de renovações anuais de certificados e reduzindo o risco de falhas na entrega de push.

Se você está usando atualmente um certificado .p12 ou .pem, migre para uma chave .p8 o mais rápido possível. Para instruções sobre como criar e fazer upload de uma chave .p8, consulte Fazer upload do seu certificado de push APNs. Para orientações da Apple sobre como gerar uma chave .p8 a partir da sua conta de desenvolvedor, consulte Communicate with APNs using authentication tokens.

Chaves .p8 versus certificados .p12

Use a tabela a seguir para comparar tipos de credenciais, expiração e como cada um aparece no dashboard.

Credencial	Expiração	Indicador de status no dashboard
Chave de autenticação .p8	Não expira	Sem indicador verde de status (isso é esperado)
Certificado de push .p12	Expira anualmente	Indicador verde quando o certificado é válido

Quando você substitui um certificado .p12 por uma chave .p8 (ou faz upload de uma nova credencial), a entrega de push pode pausar brevemente enquanto a Braze processa a alteração. Planeje atualizações durante uma janela de manutenção, quando possível.

Em Configurações > Configurações do app > Configurações das notificações por push, confirme que App Bundle ID, Team ID e Key ID (para chaves .p8) correspondem aos valores na sua conta de desenvolvedor da Apple. Vários espaços de trabalho da Braze podem usar a mesma credencial de push da Apple quando o bundle ID do app iOS é idêntico; o ambiente da credencial (desenvolvimento versus produção) deve corresponder à forma como o app foi compilado.

Apps com Braze Swift SDK 10.0.0 ou posterior podem usar o gerenciamento dinâmico de gateway APNs, que roteia tokens para o ambiente APNs correto automaticamente.

As notificações por web push não estão funcionando como esperado

Sintoma: As notificações por push do navegador não são exibidas ou as permissões do site parecem travadas.

Se você está enfrentando problemas com notificações por push no seu navegador, pode ser necessário redefinir as permissões de notificação do site e limpar o armazenamento do site. Siga as etapas abaixo para obter ajuda.

• chrome
• firefox
• safari

Métricas de abertura de push

A Braze registra uma Abertura Direta quando um usuário toca na notificação e o app inicia uma sessão. Expandir uma notificação por push rich sem abrir o app não registra uma Abertura Direta.

Se um usuário abrir o app após receber uma notificação por push sem tocar nela, a Braze pode registrar uma Abertura por Influência. Para definições e relatórios, consulte Aberturas por Influência.

Mensagens de erro de push

Sintoma: Você vê um código de erro de push específico (por exemplo, DEVICE_UNREGISTERED, Unregistered ou NotRegistered).

Para definições de códigos de erro comuns de push (incluindo DEVICE_UNREGISTERED, NotRegistered e Unregistered), consulte Mensagens de erro comuns de push.

Quando o FCM retorna erros como DEVICE_UNREGISTERED ou NotRegistered, a Braze normalmente remove o token por push afetado do perfil do usuário. Essa remoção geralmente indica que o app foi desinstalado ou que o token não é mais válido. As campanhas de Uninstall Tracking usam a mesma lógica de remoção de token em escala.