Skip to content

Solução de problemas de notificações por push

Use esta página para diagnosticar problemas de entrega e exibição de notificações por push em um dispositivo. Para verificações de entrega no dashboard (status de inscrição, Segments, limites), consulte Solução de problemas de push.

Antes de depurar, adicione-se como usuário teste e revise Envio de mensagens de teste.

Comece aqui: identifique seu sintoma

Encontre o comportamento que você está observando na tabela e siga as etapas da seção correspondente. Se não tiver certeza de qual seção se aplica, use o caminho de investigação padrão.

Sintoma Acesse
Push não recebido em uma plataforma Selecione a guia do seu SDK em Solução de problemas específica da plataforma
Quebras de linha ao redor de Liquid tags parecem incorretas ao salvar Quebras de linha em notificações por push
Verificações de entrega no dashboard (inscrição, Segment, limites) Solução de problemas de push
Deep link de push não abre corretamente Solução de problemas de deep linking
Códigos de erro comuns de push Mensagens de erro comuns de push

Caminho de investigação padrão

Use este fluxo de trabalho para cada incidente de notificação por push. Comece na etapa 1.

  1. Confirme se o dispositivo tem um token por push válido e se a permissão de push está concedida nas configurações do dispositivo.
  2. No dashboard, confirme se o usuário teste corresponde ao Segment da Campaign ou do Canvas e se não está no grupo de controle.
  3. Envie um push de teste para o dispositivo de teste.
  4. Ative o registro detalhado, reproduza o problema e consulte as orientações específicas da plataforma na guia do SDK.
  5. Se o problema persistir, entre em contato com o suporte da Braze com os registros detalhados, a plataforma, a versão do SDK e o ID da Campaign ou do Canvas.

Solução de problemas específica por plataforma

Selecione a guia do seu SDK para verificações de configuração e exibição específicas da plataforma.

Solução de problemas

Se você estiver enfrentando problemas após configurar as notificações por push, considere o seguinte:

  • As notificações por push na web exigem que seu site use HTTPS.
  • Nem todos os navegadores podem receber mensagens push. Certifique-se de que braze.isPushSupported() retorne true no navegador.
  • Alguns navegadores, como o Firefox, não exibem imagens em notificações por push. Para detalhes sobre o suporte dos navegadores, consulte a documentação MDN para imagens de Notification.
  • Se um usuário negou o acesso push de um site, ele não será solicitado novamente a conceder permissão, a menos que remova o status de negação nas preferências do navegador.

Entendendo o fluxo de trabalho de push da Braze

O serviço Firebase Cloud Messaging (FCM) é a infraestrutura do Google para notificações por push enviadas para aplicativos Android. Esta é a estrutura simplificada de como as notificações por push são ativadas para os dispositivos dos seus usuários e como a Braze pode enviar notificações por push para eles:

---
config:
  theme: mc
---
sequenceDiagram
  participant Device as User Device
  participant App as Android App
  participant BrazeSDK as Braze SDK
  participant BrazeAPI as Braze Server
  participant Firebase as Google Firebase
  Note over Device, Firebase: Register Option 1<br/>Register Automatically using `com_braze_firebase_cloud_messaging_registration_enabled` in braze.xml
  App ->> Braze: App initializes Braze with the first Braze call<br>This could be automatic session handling
  BrazeSDK ->> App: Get push token from Firebase Manager
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Register Option 2<br/>Manual registration.
  App ->> BrazeSDK: App sets `Braze.registeredPushToken`
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Push permission
  BrazeAPI ->> BrazeSDK: In-App Message containing push prompt
  BrazeSDK -> App: In-App Message is displayed
  App -> BrazeSDK: User requests permissions
  BrazeSDK -> App: Displays the Push Authorization prompt
  BrazeSDK -> BrazeAPI: If authorized and `com_braze_optin_when_push_authorized`, Opt-In value is sent.
  Note over Device, Firebase: Push Notification Is Sent
  BrazeAPI ->> Firebase: Sends push message
  Firebase ->> Device: Push message sent
  Device ->> App: Android will send the push to the App.<br>This could be blocked to Do Not Disturb, Power Saving Mode, etc.
  App ->> BrazeSDK: Message is sent to BrazeFirebaseMessagingService
  BrazeSDK ->> Device: SDK will check if the push is from Braze.<br>If so, push data is transformed into a Push Notification and displayed.

Etapa 1: Configure sua chave de API do Google Cloud

Ao desenvolver seu app, você precisará fornecer ao SDK da Braze para Android o seu ID de remetente do Firebase. Além disso, será necessário fornecer uma chave de API para aplicativos de servidor no dashboard da Braze. A Braze usará essa chave de API para enviar mensagens para seus dispositivos. Também será necessário verificar se o serviço FCM está ativado no console de desenvolvedor do Google.

Etapa 2: Os dispositivos se registram no FCM e fornecem tokens por push à Braze

Em integrações típicas, o SDK da Braze para Android lidará com o registro de dispositivos para o recurso FCM. Isso geralmente acontece imediatamente após a abertura do app pela primeira vez. Após o registro, a Braze receberá um ID de registro FCM, que é usado para enviar mensagens especificamente para esse dispositivo. Armazenaremos o ID de registro desse usuário, e ele se tornará “registrado por push” se anteriormente não tiver um token por push para nenhum dos seus apps.

Etapa 3: Lance uma Campaign de push da Braze

Quando uma Campaign de push for lançada, a Braze fará solicitações ao FCM para entregar sua mensagem. A Braze usará a chave de API copiada no dashboard para autenticar e verificar se podemos enviar notificações por push para os tokens por push fornecidos.

Etapa 4: Remova tokens inválidos

Se o FCM nos informar que qualquer um dos tokens por push para os quais estávamos tentando enviar uma mensagem é inválido, removeremos esses tokens dos perfis de usuário aos quais eles estavam associados. Se os usuários não tiverem outros tokens por push, eles não aparecerão mais como “Push Registered” na página Segments.

Para obter mais detalhes sobre o FCM, acesse Cloud messaging.

Use os registros de erros de push

A Braze fornece erros de notificações por push no registro de atividades de mensagens. Esse registro de erros fornece uma variedade de avisos que podem ser muito úteis para identificar por que suas campanhas não estão funcionando como esperado. Ao selecionar uma mensagem de erro, você será redirecionado para a documentação relevante que ajudará a solucionar um incidente específico.

Registro de atividades de mensagens da Braze mostrando entradas de erros de notificações por push.

Solução de problemas

O push não está sendo enviado

Suas mensagens push podem não estar sendo enviadas devido às seguintes situações:

  • Suas credenciais existem no ID de projeto errado do Google Cloud Platform (ID de remetente errado).
  • Suas credenciais têm o escopo de permissão incorreto.
  • Você fez upload de credenciais erradas para o espaço de trabalho errado da Braze (ID de remetente errado).

Para outros problemas que podem impedir o envio de uma mensagem push, consulte Guia do usuário: solução de problemas de notificações por push.

Nenhum usuário “push registrado” é exibido no dashboard da Braze (antes do envio de mensagens)

Confirme se o seu app está configurado corretamente para permitir notificações por push. Os pontos de falha comuns a serem verificados incluem:

ID do remetente incorreto

Verifique se o ID do remetente FCM correto está incluído no arquivo braze.xml. Um ID de remetente incorreto levará a erros MismatchSenderID relatados no registro de atividade de mensagens do dashboard.

O registro da Braze não está ocorrendo

Como o registro do FCM é feito fora da Braze, a falha no registro só pode ocorrer em dois lugares:

  1. Durante o registro no FCM
  2. Ao passar o token por push gerado pelo FCM para a Braze

Recomendamos definir um ponto de interrupção ou registro para confirmar que o token por push gerado pelo FCM está sendo enviado à Braze. Se um token não for gerado corretamente ou de forma alguma, recomendamos consultar a documentação do FCM.

O Google Play Services não está presente

Para que o push do FCM funcione, o Google Play Services deve estar presente no dispositivo. Se o Google Play Services não estiver em um dispositivo, o registro push não ocorrerá.

O dispositivo não está conectado à internet

Verifique se o seu dispositivo tem boa conectividade com a internet e se não está enviando tráfego de rede por meio de um proxy.

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

Verifique se com_braze_handle_push_deep_links_automatically está definido como true ou false. Para permitir que a Braze abra automaticamente o app e quaisquer deep links quando uma notificação por push for tocada, defina com_braze_handle_push_deep_links_automatically como true no seu arquivo braze.xml.

Se com_braze_handle_push_deep_links_automatically estiver definido como o padrão false, você precisará usar um retorno de chamada do Braze Push para ouvir e tratar as intenções recebidas e abertas de push.

As notificações por push sofreram bounce

Se uma notificação por push não for entregue, verifique se não houve bounce no console de desenvolvedor. A seguir estão as descrições de erros comuns que podem ser registrados no console de desenvolvedor:

Erro: MismatchSenderID

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

Erro: InvalidRegistration

InvalidRegistration pode ser causado por um token por push malformado.

  1. Certifique-se de passar um token por push válido para a Braze a partir do Firebase Cloud Messaging.

Erro: NotRegistered

  1. NotRegistered também pode ocorrer quando há vários registros e um segundo registro invalida o primeiro token.

Notificações por push enviadas, mas não exibidas nos dispositivos dos usuários

Há alguns motivos pelos quais isso pode estar ocorrendo:

O aplicativo foi encerrado à força

Se você forçar o encerramento do aplicativo por meio das configurações do sistema, as notificações por push não serão enviadas. Ao iniciar o app novamente, seu dispositivo será reativado para receber notificações por push.

BrazeFirebaseMessagingService não registrado

O BrazeFirebaseMessagingService deve ser registrado corretamente em AndroidManifest.xml para que as notificações por push sejam exibidas:

1
2
3
4
5
6

<service android:name="com.braze.push.BrazeFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

O firewall está bloqueando o push

Se estiver testando o push por Wi-Fi, seu firewall pode estar bloqueando as portas necessárias para que o FCM receba mensagens. Confirme se as portas 5228, 5229 e 5230 estão abertas. Além disso, como o FCM não especifica seus IPs, você também deve permitir que seu firewall aceite conexões de saída para todos os endereços IP contidos nos blocos de IPs listados no ASN do Google de 15169.

Fábrica de notificação personalizada retornando nulo

Se você tiver implementado uma fábrica de notificações personalizada, certifique-se de que ela não esteja retornando null. Isso fará com que as notificações não sejam exibidas.

Os usuários “push registrados” não estão mais ativados após o envio de mensagens

Há alguns motivos pelos quais isso pode estar acontecendo:

O aplicativo foi desinstalado

Os usuários desinstalaram o aplicativo. Isso invalidará o token por push FCM deles.

Chave de servidor do Firebase Cloud Messaging inválida

A chave do servidor do Firebase Cloud Messaging fornecida no dashboard da Braze é inválida. O ID do remetente fornecido deve corresponder àquele referenciado no arquivo braze.xml do seu app. A chave do servidor e o ID do remetente podem ser encontrados aqui no seu console do Firebase:

A plataforma Firebase, em "Settings" e depois em "Cloud Messaging", exibirá o ID e a chave do servidor.

Cliques em push não registrados

Se os cliques em push não estiverem sendo registrados, é possível que os dados de cliques push ainda não tenham sido enviados aos nossos servidores. O SDK da Braze para Android pode limitar a frequência dos envios.

Se você implementou um tratamento de push personalizado, certifique-se de que está preservando corretamente a análise de dados nativa de push.

O registro de cliques em push é uma operação de rede e está sujeito a limitações de conectividade. Dessa forma, embora o SDK da Braze para Android tente acomodar falhas de rede e reenvie solicitações com falha, alguma perda de eventos é esperada.

Os deep links podem ser testados com o ADB. Recomendamos testar seu deep link com o seguinte comando:

adb shell am start -W -a android.intent.action.VIEW -d "THE_DEEP_LINK" THE_PACKAGE_NAME

Se o deep link não funcionar, ele pode estar mal configurado. Um deep link mal configurado não funcionará quando enviado por meio do Braze push.

Verificar a lógica de tratamento personalizado

Se o deep link funcionar corretamente com o ADB, mas não funcionar com o Braze push, verifique se foi implementado algum tratamento personalizado de abertura de push. Se for o caso, verifique se o código de tratamento personalizado trata corretamente o deep link de entrada.

Desativar o comportamento da pilha de retorno

Se o deep link funcionar corretamente com o ADB, mas não funcionar com o Braze push, tente desativar a pilha de retorno. Para fazer isso, atualize seu arquivo braze.xml para incluir:

1

<bool name="com_braze_push_deep_link_back_stack_activity_enabled">false</bool>

Entendendo o fluxo de trabalho da Braze/APNs

O serviço de Notificações por Push da Apple (APN) é a infraestrutura para enviar notificações por push a aplicativos executados nas plataformas da Apple. Veja a seguir a estrutura simplificada de como as notificações por push são ativadas para os dispositivos dos seus usuários e como a Braze pode enviar notificações por push para eles:

  1. Você configura o certificado push e o perfil de provisionamento
  2. Os dispositivos se registram no APNs e fornecem à Braze os tokens por push
  3. Você lança uma Campaign de push na Braze
  4. A Braze remove os tokens inválidos

Etapa 1: Configurando o certificado push e o perfil de provisionamento

Para desenvolver seu app, crie um certificado SSL para ativar notificações por push. Esse certificado é incluído no perfil de provisionamento com o qual seu app é compilado e também deve ser enviado ao dashboard da Braze. O certificado permite que a Braze informe ao APNs que está autorizada a enviar notificações por push em seu nome.

Existem dois tipos de perfis de provisionamento e certificados: desenvolvimento e distribuição. Recomendamos usar apenas perfis e certificados de distribuição para evitar qualquer confusão. Se você optar por usar perfis e certificados diferentes para desenvolvimento e distribuição, certifique-se de que o certificado enviado ao dashboard corresponda ao perfil de provisionamento que você está usando no momento.

Etapa 2: Os dispositivos se registram no APNs e fornecem tokens por push à Braze

Quando os usuários abrem seu app, eles são solicitados a aceitar notificações por push. Se aceitarem, o APNs gera um token por push para aquele dispositivo específico. O SDK Swift envia imediata e assincronamente o token por push para apps que usam a política de envio automático padrão. Depois que temos um token por push associado a um usuário, ele aparece como “Push Registered” no dashboard, no perfil do usuário, na guia Engagement, e se torna elegível para receber notificações por push de Campaigns da Braze.

Considerações sobre a geração de tokens por push

  • Se os usuários instalarem seu app em outro dispositivo, a Braze cria e captura outro token da mesma forma.
  • Se os usuários reinstalarem seu app, o SDK gera um novo token e o envia à Braze. No entanto, o APNs e a Braze ainda podem registrar o token original como válido.
  • Se os usuários desinstalarem seu app, a Braze não recebe uma notificação imediatamente, e o token ainda aparece como válido até que o APNs o retire.
  • Em algum momento, o APNs retira tokens antigos. A Braze não controla nem tem visibilidade sobre esse processo.

Etapa 3: Lançando uma Campaign de push da Braze

Quando uma Campaign de push é lançada, a Braze faz solicitações ao APNs para entregar sua mensagem. Especificamente, as solicitações são enviadas ao APNs para cada token por push válido atual, a menos que Enviar para o dispositivo mais recente do usuário esteja selecionado. Depois que a Braze recebe uma resposta de sucesso do APNs, ela registra uma entrega bem-sucedida no perfil do usuário, embora o usuário possa não ter recebido a mensagem real por motivos como:

  • O dispositivo está desligado.
  • O dispositivo não está conectado à internet (Wi-Fi ou celular).
  • O app foi desinstalado recentemente.

A Braze usa o certificado SSL de push enviado ao dashboard para autenticar e verificar que está autorizada a enviar notificações por push para os tokens por push fornecidos. Se um dispositivo estiver online, a notificação deve ser recebida logo após o envio da Campaign. Observe que a Braze define a data de expiração padrão do APNs para notificações como 30 dias.

Etapa 4: Removendo tokens inválidos

Se o APNs nos informar que algum dos tokens por push para os quais tentamos enviar uma mensagem é inválido, removemos esses tokens dos perfis de usuário aos quais estavam associados.

Usando os logs de erros de push

O Registro de atividade de mensagens permite que você veja quaisquer mensagens (especialmente mensagens de erro) associadas às suas Campaigns e envios, incluindo erros de notificação por push. Esse log de erros fornece uma variedade de avisos que podem ser muito úteis para identificar por que suas Campaigns não estão funcionando como esperado. Selecionar uma mensagem de erro redireciona você para a documentação relevante para ajudar na solução de problemas de um incidente específico.

Logs de erros de push exibindo o horário em que o erro ocorreu, o nome do app, o canal, o tipo de erro e a mensagem de erro.

Erros comuns que você pode ver aqui incluem notificações específicas do usuário, como “Received Unregistered Sending to Push Token”.

Além disso, a Braze também fornece um changelog de push no perfil do usuário, na guia Engagement. Esse changelog oferece insights sobre o comportamento de registro de push, como invalidação de token, erros de registro de push, tokens sendo movidos para novos usuários, etc.

Guia Engagement do perfil de usuário da Braze mostrando o changelog de registro de push.

Erros do Registro de atividade de mensagens

Received unregistered sending to push token

  • Certifique-se de que o token por push enviado à Braze pelo método AppDelegate.braze?.notifications.register(deviceToken:) é válido. Você pode verificar no Registro de atividade de mensagens para ver o token por push. Ele deve se parecer com algo como 6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6, uma string longa contendo uma mistura de letras e números. Se seu token por push parecer diferente, verifique seu código para enviar os tokens por push à Braze.
  • Certifique-se de que seu perfil de provisionamento de push corresponde ao ambiente em que você está testando. Certificados universais podem ser configurados no dashboard da Braze para enviar ao ambiente de APNs de desenvolvimento ou produção. Usar um certificado de desenvolvimento para um app de produção ou um certificado de produção para um app de desenvolvimento não funciona.
  • Verifique se o token por push que você enviou à Braze corresponde ao perfil de provisionamento usado para compilar o app do qual o token por push foi enviado.

Device token not for topic

O APNs retorna DeviceTokenNotForTopic (status HTTP 400) quando o token por push não corresponde ao tópico (bundle ID) configurado para suas credenciais. A Braze pode exibir isso no Registro de atividade de mensagens ou nos logs de entrega de push como DeviceTokenNotForTopic.

Para resolver a incompatibilidade:

  1. Confirme que o bundle ID do app corresponde ao App Bundle ID na Braze (Configurações > Configurações do app > Configurações de notificação por push).
  2. Verifique se o perfil de provisionamento usado para compilar o app inclui a capacidade de push para esse bundle ID.
  3. Confirme que a credencial de push enviada à Braze corresponde ao ambiente do app (desenvolvimento versus produção).
  4. Para chaves .p8, verifique se o Team ID e o Key ID na Braze correspondem à sua conta Apple Developer.
  5. Reenvie uma chave .p8 válida ou um certificado .p12 se as credenciais foram rotacionadas ou revogadas.

Prefira chaves de autenticação .p8 quando possível. Para tipos de credenciais e indicadores de status no dashboard, consulte Migrar para uma chave de autenticação .p8.

BadDeviceToken sending to push token

O BadDeviceToken é um código de erro do APNs e não se origina da Braze. Pode haver vários motivos para essa resposta ser retornada, incluindo os seguintes:

  • O app recebeu um token por push que era inválido para as credenciais carregadas no dashboard.
  • O push foi desativado para este espaço de trabalho.
  • O usuário optou por não receber push.
  • O app foi desinstalado.
  • A Apple atualizou o token por push, o que invalidou o token antigo.
  • O app foi criado para um ambiente de produção, mas as credenciais de push carregadas na Braze estão configuradas para um ambiente de desenvolvimento (ou vice-versa).

Problemas de registro de push

Nenhum prompt de registro de push

Se o aplicativo não solicitar que você se registre para notificações por push, provavelmente há um problema com a integração do registro de push. Certifique-se de ter seguido nossa documentação e integrado corretamente nosso registro de push. Você também pode definir breakpoints no seu código para garantir que o código de registro de push está sendo executado.

Nenhum usuário “push registered” aparecendo no dashboard (antes de enviar mensagens)

Certifique-se de que seu app está configurado corretamente para permitir notificações por push. Pontos comuns de falha a verificar incluem:

  • Verifique se seu app está solicitando que você permita notificações por push. Normalmente, esse prompt aparece na primeira abertura do app, mas pode ser programado para aparecer em outro lugar. Se ele não aparecer onde deveria, o problema provavelmente está na configuração básica das capacidades de push do seu app.
    • Verifique se as etapas de integração de push foram concluídas com sucesso.
    • Verifique se o perfil de provisionamento com o qual seu app foi compilado inclui permissões para push. Certifique-se de que está baixando todos os perfis de provisionamento disponíveis da sua conta Apple Developer. Para confirmar, siga estas etapas:
      1. No Xcode, navegue até Preferences > Accounts (ou use o atalho de teclado Command+,).
      2. Selecione o Apple ID que você usa para sua conta de desenvolvedor e clique em View Details.
      3. Na próxima página, clique em Refresh e confirme que está baixando todos os perfis de provisionamento disponíveis.
  • Verifique se você ativou corretamente a capacidade de push no seu app.
  • Verifique se seu perfil de provisionamento de push corresponde ao ambiente em que você está testando. Certificados universais podem ser configurados no dashboard da Braze para enviar ao ambiente de APNs de desenvolvimento ou produção. Usar um certificado de desenvolvimento para um app de produção ou um certificado de produção para um app de desenvolvimento não funciona.
  • Verifique se você está chamando nosso método registerPushToken definindo um breakpoint no seu código.
  • Certifique-se de que está testando usando um dispositivo (push não funciona em um simulador) e que tem boa conectividade de rede.

Notificações por push enviadas mas não exibidas nos dispositivos dos usuários

Usuários “push registered” não mais habilitados após o envio de mensagens

Isso provavelmente indica que o usuário tinha um token por push inválido. Isso pode acontecer por vários motivos:

Incompatibilidade entre certificado do dashboard e do app

Se o certificado push que você enviou ao dashboard não for o mesmo do perfil de provisionamento com o qual seu app foi compilado, o APNs rejeitará o token. Verifique se você enviou o certificado correto e complete outra sessão no app antes de tentar outra notificação de teste.

O aplicativo foi desinstalado

Se um usuário desinstalou seu aplicativo, o token por push dele será inválido e removido no próximo envio.

Regenerando seu perfil de provisionamento

Como último recurso, começar do zero e criar um perfil de provisionamento totalmente novo pode resolver erros de configuração que surgem ao trabalhar com múltiplos ambientes, perfis e apps ao mesmo tempo. Existem muitas “partes móveis” na configuração de notificações por push, então às vezes é melhor recomeçar do início. Isso também ajudará a isolar o problema se você precisar continuar a solução de problemas.

Mensagens não entregues a usuários “push registered”

O app está em primeiro plano

Em versões do iOS que não integram push via o framework UserNotifications, se o app estiver em primeiro plano quando a mensagem push for recebida, ela não será exibida. Você deve colocar o app em segundo plano nos seus dispositivos de teste antes de enviar mensagens de teste.

Notificação de teste agendada incorretamente

Verifique o cronograma que você definiu para sua mensagem de teste. Se estiver configurado para entrega no fuso local ou com Intelligent Timing, você pode simplesmente ainda não ter recebido a mensagem (ou o app estava em primeiro plano quando ela foi recebida).

Usuário não “push registered” para o app sendo testado

Verifique o perfil do usuário para quem você está tentando enviar uma mensagem de teste. Na guia Engagement, deve haver uma lista de “pushable apps.” Verifique se o app para o qual você está tentando enviar mensagens de teste está nessa lista. Os usuários aparecerão como “Push Registered” se tiverem um token por push para qualquer app no seu espaço de trabalho, então isso pode ser um falso positivo.

O seguinte indicaria um problema com o registro de push ou que o token do usuário foi retornado à Braze como inválido pelo APNs após o envio:

Um perfil de usuário exibindo as configurações de contato de um usuário. Em Push, "No Apps" é exibido.

Cliques em push não registrados

  • Certifique-se de ter seguido as etapas de integração de push.
  • A Braze não processa notificações por push recebidas silenciosamente em primeiro plano (comportamento padrão de push em primeiro plano antes do framework UserNotifications). Isso significa que os links não serão abertos e os cliques em push não serão registrados. Se seu aplicativo ainda não integrou o framework UserNotifications, a Braze não processará notificações por push quando o estado do aplicativo for UIApplicationStateActive. Certifique-se de que seu app não atrasa chamadas aos métodos de processamento de push; caso contrário, o SDK Swift pode tratar as notificações por push como eventos silenciosos de push em primeiro plano e não processá-las.

Para uma solução de problemas abrangente em todos os canais — incluindo links universais, esquemas personalizados, e-mail e provedores terceiros como Branch — consulte Solução de problemas de deep linking.

Links em notificações por push precisam ser compatíveis com ATS para serem abertos em web views. Certifique-se de que seus links da web usam HTTPS. Para saber mais, consulte Conformidade com ATS.

A maior parte do código que processa deep links também processa aberturas de push. Primeiro, certifique-se de que as aberturas de push estão sendo registradas. Se não estiverem, corrija esse problema (pois a correção geralmente também resolve o processamento de links).

Se as aberturas estão sendo registradas, verifique se o problema é com o deep link em geral ou com o processamento de deep link no clique de push. Para isso, teste se um deep link a partir de um clique em uma mensagem no app funciona.

Entendendo o fluxo de trabalho de push da Braze

O serviço Firebase Cloud Messaging (FCM) é a infraestrutura do Google para notificações por push enviadas para aplicativos Android. Esta é a estrutura simplificada de como as notificações por push são ativadas para os dispositivos dos seus usuários e como a Braze pode enviar notificações por push para eles:

---
config:
  theme: mc
---
sequenceDiagram
  participant Device as User Device
  participant App as Android App
  participant BrazeSDK as Braze SDK
  participant BrazeAPI as Braze Server
  participant Firebase as Google Firebase
  Note over Device, Firebase: Register Option 1<br/>Register Automatically using `com_braze_firebase_cloud_messaging_registration_enabled` in braze.xml
  App ->> Braze: App initializes Braze with the first Braze call<br>This could be automatic session handling
  BrazeSDK ->> App: Get push token from Firebase Manager
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Register Option 2<br/>Manual registration.
  App ->> BrazeSDK: App sets `Braze.registeredPushToken`
  BrazeSDK ->> BrazeAPI: Send push token to Braze Server
  Note right of BrazeAPI: Braze will remove push token from any<br>other user who may have previously<br> been logged in on the same device.
  Note over Device, Firebase: Push permission
  BrazeAPI ->> BrazeSDK: In-App Message containing push prompt
  BrazeSDK -> App: In-App Message is displayed
  App -> BrazeSDK: User requests permissions
  BrazeSDK -> App: Displays the Push Authorization prompt
  BrazeSDK -> BrazeAPI: If authorized and `com_braze_optin_when_push_authorized`, Opt-In value is sent.
  Note over Device, Firebase: Push Notification Is Sent
  BrazeAPI ->> Firebase: Sends push message
  Firebase ->> Device: Push message sent
  Device ->> App: Android will send the push to the App.<br>This could be blocked to Do Not Disturb, Power Saving Mode, etc.
  App ->> BrazeSDK: Message is sent to BrazeFirebaseMessagingService
  BrazeSDK ->> Device: SDK will check if the push is from Braze.<br>If so, push data is transformed into a Push Notification and displayed.

Etapa 1: Configure sua chave de API do Google Cloud

Ao desenvolver seu app, você precisará fornecer ao SDK da Braze para Android o seu ID de remetente do Firebase. Além disso, será necessário fornecer uma chave de API para aplicativos de servidor no dashboard da Braze. A Braze usará essa chave de API para enviar mensagens para seus dispositivos. Também será necessário verificar se o serviço FCM está ativado no console de desenvolvedor do Google.

Etapa 2: Os dispositivos se registram no FCM e fornecem tokens por push à Braze

Em integrações típicas, o SDK da Braze para Android lidará com o registro de dispositivos para o recurso FCM. Isso geralmente acontece imediatamente após a abertura do app pela primeira vez. Após o registro, a Braze receberá um ID de registro FCM, que é usado para enviar mensagens especificamente para esse dispositivo. Armazenaremos o ID de registro desse usuário, e ele se tornará “registrado por push” se anteriormente não tiver um token por push para nenhum dos seus apps.

Etapa 3: Lance uma Campaign de push da Braze

Quando uma Campaign de push for lançada, a Braze fará solicitações ao FCM para entregar sua mensagem. A Braze usará a chave de API copiada no dashboard para autenticar e verificar se podemos enviar notificações por push para os tokens por push fornecidos.

Etapa 4: Remova tokens inválidos

Se o FCM nos informar que qualquer um dos tokens por push para os quais estávamos tentando enviar uma mensagem é inválido, removeremos esses tokens dos perfis de usuário aos quais eles estavam associados. Se os usuários não tiverem outros tokens por push, eles não aparecerão mais como “Push Registered” na página Segments.

Para obter mais detalhes sobre o FCM, acesse Cloud messaging.

Use os registros de erros de push

A Braze fornece erros de notificações por push no registro de atividades de mensagens. Esse registro de erros fornece uma variedade de avisos que podem ser muito úteis para identificar por que suas campanhas não estão funcionando como esperado. Ao selecionar uma mensagem de erro, você será redirecionado para a documentação relevante que ajudará a solucionar um incidente específico.

Registro de atividades de mensagens da Braze mostrando entradas de erros de notificações por push.

Solução de problemas

O push não está sendo enviado

Suas mensagens push podem não estar sendo enviadas devido às seguintes situações:

  • Suas credenciais existem no ID de projeto errado do Google Cloud Platform (ID de remetente errado).
  • Suas credenciais têm o escopo de permissão incorreto.
  • Você fez upload de credenciais erradas para o espaço de trabalho errado da Braze (ID de remetente errado).

Para outros problemas que podem impedir o envio de uma mensagem push, consulte Guia do usuário: solução de problemas de notificações por push.

Nenhum usuário “push registrado” é exibido no dashboard da Braze (antes do envio de mensagens)

Confirme se o seu app está configurado corretamente para permitir notificações por push. Os pontos de falha comuns a serem verificados incluem:

ID do remetente incorreto

Verifique se o ID do remetente FCM correto está incluído no arquivo braze.xml. Um ID de remetente incorreto levará a erros MismatchSenderID relatados no registro de atividade de mensagens do dashboard.

O registro da Braze não está ocorrendo

Como o registro do FCM é feito fora da Braze, a falha no registro só pode ocorrer em dois lugares:

  1. Durante o registro no FCM
  2. Ao passar o token por push gerado pelo FCM para a Braze

Recomendamos definir um ponto de interrupção ou registro para confirmar que o token por push gerado pelo FCM está sendo enviado à Braze. Se um token não for gerado corretamente ou de forma alguma, recomendamos consultar a documentação do FCM.

O Google Play Services não está presente

Para que o push do FCM funcione, o Google Play Services deve estar presente no dispositivo. Se o Google Play Services não estiver em um dispositivo, o registro push não ocorrerá.

O dispositivo não está conectado à internet

Verifique se o seu dispositivo tem boa conectividade com a internet e se não está enviando tráfego de rede por meio de um proxy.

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

Verifique se com_braze_handle_push_deep_links_automatically está definido como true ou false. Para permitir que a Braze abra automaticamente o app e quaisquer deep links quando uma notificação por push for tocada, defina com_braze_handle_push_deep_links_automatically como true no seu arquivo braze.xml.

Se com_braze_handle_push_deep_links_automatically estiver definido como o padrão false, você precisará usar um retorno de chamada do Braze Push para ouvir e tratar as intenções recebidas e abertas de push.

As notificações por push sofreram bounce

Se uma notificação por push não for entregue, verifique se não houve bounce no console de desenvolvedor. A seguir estão as descrições de erros comuns que podem ser registrados no console de desenvolvedor:

Erro: MismatchSenderID

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

Erro: InvalidRegistration

InvalidRegistration pode ser causado por um token por push malformado.

  1. Certifique-se de passar um token por push válido para a Braze a partir do Firebase Cloud Messaging.

Erro: NotRegistered

  1. NotRegistered também pode ocorrer quando há vários registros e um segundo registro invalida o primeiro token.

Notificações por push enviadas, mas não exibidas nos dispositivos dos usuários

Há alguns motivos pelos quais isso pode estar ocorrendo:

O aplicativo foi encerrado à força

Se você forçar o encerramento do aplicativo por meio das configurações do sistema, as notificações por push não serão enviadas. Ao iniciar o app novamente, seu dispositivo será reativado para receber notificações por push.

BrazeFirebaseMessagingService não registrado

O BrazeFirebaseMessagingService deve ser registrado corretamente em AndroidManifest.xml para que as notificações por push sejam exibidas:

1
2
3
4
5
6

<service android:name="com.braze.push.BrazeFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

O firewall está bloqueando o push

Se estiver testando o push por Wi-Fi, seu firewall pode estar bloqueando as portas necessárias para que o FCM receba mensagens. Confirme se as portas 5228, 5229 e 5230 estão abertas. Além disso, como o FCM não especifica seus IPs, você também deve permitir que seu firewall aceite conexões de saída para todos os endereços IP contidos nos blocos de IPs listados no ASN do Google de 15169.

Fábrica de notificação personalizada retornando nulo

Se você tiver implementado uma fábrica de notificações personalizada, certifique-se de que ela não esteja retornando null. Isso fará com que as notificações não sejam exibidas.

Os usuários “push registrados” não estão mais ativados após o envio de mensagens

Há alguns motivos pelos quais isso pode estar acontecendo:

O aplicativo foi desinstalado

Os usuários desinstalaram o aplicativo. Isso invalidará o token por push FCM deles.

Chave de servidor do Firebase Cloud Messaging inválida

A chave do servidor do Firebase Cloud Messaging fornecida no dashboard da Braze é inválida. O ID do remetente fornecido deve corresponder àquele referenciado no arquivo braze.xml do seu app. A chave do servidor e o ID do remetente podem ser encontrados aqui no seu console do Firebase:

A plataforma Firebase, em "Settings" e depois em "Cloud Messaging", exibirá o ID e a chave do servidor.

Cliques em push não registrados

Se os cliques em push não estiverem sendo registrados, é possível que os dados de cliques push ainda não tenham sido enviados aos nossos servidores. O SDK da Braze para Android pode limitar a frequência dos envios.

Se você implementou um tratamento de push personalizado, certifique-se de que está preservando corretamente a análise de dados nativa de push.

O registro de cliques em push é uma operação de rede e está sujeito a limitações de conectividade. Dessa forma, embora o SDK da Braze para Android tente acomodar falhas de rede e reenvie solicitações com falha, alguma perda de eventos é esperada.

Os deep links podem ser testados com o ADB. Recomendamos testar seu deep link com o seguinte comando:

adb shell am start -W -a android.intent.action.VIEW -d "THE_DEEP_LINK" THE_PACKAGE_NAME

Se o deep link não funcionar, ele pode estar mal configurado. Um deep link mal configurado não funcionará quando enviado por meio do Braze push.

Verificar a lógica de tratamento personalizado

Se o deep link funcionar corretamente com o ADB, mas não funcionar com o Braze push, verifique se foi implementado algum tratamento personalizado de abertura de push. Se for o caso, verifique se o código de tratamento personalizado trata corretamente o deep link de entrada.

Desativar o comportamento da pilha de retorno

Se o deep link funcionar corretamente com o ADB, mas não funcionar com o Braze push, tente desativar a pilha de retorno. Para fazer isso, atualize seu arquivo braze.xml para incluir:

1

<bool name="com_braze_push_deep_link_back_stack_activity_enabled">false</bool>

Solução de problemas

Tocar na notificação por push não abre o app

No Android, se tocar em uma notificação por push traz automaticamente o app para o primeiro plano e abre o deep link é controlado pela flag nativa com_braze_handle_push_deep_links_automatically, que tem o valor padrão false.

Com o padrão false:

  • O SDK nativo ainda envia um broadcast BRAZE_PUSH_CLICKED e o listener push_opened do Dart ainda é acionado conforme esperado.
  • O SDK nativo não chama startActivity(), então o app não é trazido para o primeiro plano e o deep link não é seguido automaticamente.

Se esses dois comportamentos correspondem ao que você está observando, a configuração da flag provavelmente é a causa. Para confirmar, verifique os logs do dispositivo em busca de uma entrada BrazePushReceiver tratando com.braze.action.BRAZE_PUSH_CLICKED, seguida de um evento push_opened nos logs do Flutter, sem uma abertura correspondente do app.

Para corrigir isso, defina com_braze_handle_push_deep_links_automatically como true no seu braze.xml:

1

<bool name="com_braze_handle_push_deep_links_automatically">true</bool>

Para saber mais, consulte Adicionar deep links (Android) no guia de notificações por push do Flutter.

Outros problemas de entrega e registro de push

Como o SDK Flutter da Braze para Android é construído sobre o SDK nativo Android da Braze, a maioria dos outros problemas de entrega, registro e logging de push (como incompatibilidade de sender ID, ausência do Google Play Services ou BrazeFirebaseMessagingService não registrado) também se aplica a apps Flutter. Para saber mais, consulte o guia de solução de problemas nativo do Android.

Solução de problemas

Push não aparece após o app ser fechado pelo alternador de tarefas

Se você observar que as notificações por push não aparecem mais após o app ser fechado pelo alternador de tarefas, seu app provavelmente está no modo Debug. O .NET MAUI adiciona scaffolding no modo Debug que impede que os apps recebam push após o processo ser encerrado. Se você executar seu app no modo Release, deverá ver push mesmo após o app ser fechado pelo alternador de tarefas.

Fábrica de notificação personalizada não configurada corretamente

Fábricas de notificação personalizadas (e todos os delegates) devem estender Java.Lang.Object para funcionar corretamente na interface entre C# e Java. Consulte Xamarin sobre a implementação de interfaces Java para mais informações.

Quebras de linha em notificações por push

Ao redigir notificações por push com Liquid tags, as quebras de linha adjacentes às Liquid tags são automaticamente removidas antes do envio da mensagem. No criador de notificações por push, essas quebras de linha são adicionadas novamente para que sua mensagem permaneça legível durante a edição. Se você notar quebras de linha ao redor das Liquid tags ao salvar sua mensagem, esse é o comportamento esperado.
New Stuff!