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íficos por plataforma |
| Quebras de linha ao redor de Liquid tags ficam 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 a partir 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.
- Confirme que o dispositivo tem um token por push válido e que a permissão de push está concedida nas configurações do dispositivo.
- No dashboard, confirme que o usuário teste corresponde ao Segment da Campaign ou Canvas e não está no grupo de controle.
- Envie um push de teste para o dispositivo de teste.
- Ative o registro detalhado, reproduza o problema e consulte as orientações específicas da plataforma na guia do SDK.
- 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 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ê está enfrentando problemas após configurar as notificações por push, considere o seguinte:
- As notificações por push na web exigem que seu site utilize HTTPS.
- Nem todos os navegadores podem receber mensagens push. Verifique se
braze.isPushSupported()retornatrueno navegador. - Alguns navegadores, como o Firefox, não exibem imagens nas notificações por push. Para detalhes sobre o suporte do navegador, consulte a documentação MDN para imagens de notificação.
- Se um usuário negou o acesso push a um site, ele não será solicitado novamente para 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 Firebase Cloud Messaging (FCM) é a infraestrutura do Google para notificações por push enviadas a aplicativos Android. Aqui está 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 Android da Braze o seu ID de remetente do Firebase. Além disso, será necessário fornecer uma chave de API para aplicativos de servidor ao dashboard da Braze. A Braze usará essa chave de API para enviar mensagens aos seus dispositivos. Você também precisará verificar se o serviço FCM está ativado no console do Google Developer.
Um erro comum durante esta etapa é usar a chave de API do identificador do app em vez da chave da API REST.
Etapa 2: Os dispositivos se registram no FCM e fornecem tokens por push à Braze
Em integrações típicas, o SDK Android da Braze cuidará do registro dos dispositivos para a funcionalidade FCM. Isso geralmente acontece imediatamente ao abrir o app pela primeira vez. Após o registro, a Braze receberá um ID de registro do FCM, que é usado para enviar mensagens especificamente para aquele dispositivo. Armazenaremos o ID de registro desse usuário, e ele passará a ter o status de “push registrado” caso não possuísse anteriormente um token por push para nenhum dos seus apps.
Etapa 3: Lance uma Campaign de push na Braze
Quando uma Campaign de push é lançada, a Braze faz solicitações ao FCM para entregar sua mensagem. A Braze usa a chave de API copiada no dashboard para autenticar e verificar que é possível enviar notificações por push para os tokens por push fornecidos.
Etapa 4: Remova tokens inválidos
Se o FCM 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. Se os usuários não tiverem outros tokens por push, eles não aparecerão mais como “Push Registered” na página de Segments.
Para mais detalhes sobre o FCM, visite Cloud messaging.
Revise os erros de push
Os erros de notificações por push de uma Campaign ou Canvas aparecem em Observabilidade de envio de mensagens.
Solução de problemas
Push não está sendo enviado
Suas mensagens de push podem não estar sendo enviadas devido às seguintes situações:
- Suas credenciais existem no projeto do Google Cloud Platform errado (sender ID incorreto).
- Suas credenciais têm o escopo de permissão errado.
- Você fez upload de credenciais erradas para o espaço de trabalho errado da Braze (sender ID incorreto).
Para outros problemas que podem impedir o envio de uma mensagem de push, consulte Guia do Usuário: Solução de problemas de notificações por push.
Nenhum usuário “push registered” aparecendo no dashboard da Braze (antes de enviar mensagens)
Confirme se o seu app está configurado corretamente para permitir notificações por push. Pontos de falha comuns a serem verificados incluem:
Sender ID incorreto
Verifique se o sender ID correto do FCM está incluído no arquivo braze.xml. Um sender ID incorreto leva a erros MismatchSenderID. Revise-os em Observabilidade de mensagens.
Registro na Braze não está ocorrendo
Como o registro do FCM é feito fora da Braze, a falha no registro pode ocorrer apenas em dois lugares:
- Durante o registro com o FCM
- Ao passar o token de push gerado pelo FCM para a Braze
Recomendamos definir um breakpoint ou registrar logs para confirmar que o token de push gerado pelo FCM está sendo enviado para a Braze. Se um token não for gerado corretamente ou não for gerado, recomendamos consultar a documentação do FCM.
Google Play Services não 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 de push não ocorrerá.
O Google Play Services não é instalado em emuladores Android sem as APIs do Google instaladas.
Dispositivo não conectado à internet
Verifique se seu dispositivo tem boa conectividade com a internet e não está enviando tráfego de rede por meio de um proxy.
Tocar na 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 com o valor padrão false, você precisará usar um Braze Push Callback para escutar e tratar os intents de push recebido e aberto.
Notificações por push com bounce
Se uma notificação por push não foi entregue, verifique se ela não sofreu bounce consultando o console de desenvolvedor. A seguir estão 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 sender ID do Firebase e a chave de API do FCM estão corretos.
Erro: InvalidRegistration
InvalidRegistration pode ser causado por um token de push malformado.
- Certifique-se de passar um token de push válido para a Braze a partir do Firebase Cloud Messaging.
Erro: NotRegistered
NotRegisteredtambém pode ocorrer quando múltiplos registros acontecem e um segundo registro invalida o primeiro token.
Notificações por push enviadas, mas não exibidas nos dispositivos dos usuários
Existem algumas razões pelas quais isso pode estar ocorrendo:
O app foi encerrado forçadamente
Se você encerrar forçadamente o app pelas configurações do sistema, suas notificações por push não serão enviadas. Abrir o app novamente reativará a capacidade do dispositivo de receber notificações por push.
BrazeFirebaseMessagingService não registrado
O BrazeFirebaseMessagingService deve ser devidamente registrado no AndroidManifest.xml para que as notificações por push apareçam:
<service android:name="com.braze.push.BrazeFirebaseMessagingService"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
Firewall está bloqueando o push
Se você está testando push por Wi-Fi, seu firewall pode estar bloqueando as portas necessárias para o FCM receber mensagens. Confirme que 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 IP listados no ASN do Google de 15169.
Fábrica de notificações personalizada retornando null
Se você implementou uma fábrica de notificações personalizada, certifique-se de que ela não está retornando null. Isso fará com que as notificações não sejam exibidas.
Usuários “push registered” não estão mais ativados após o envio de mensagens
Existem algumas razões pelas quais isso pode estar acontecendo:
O app foi desinstalado
Os usuários desinstalaram o app. Isso invalidará o token de push do FCM deles.
Chave do servidor do Firebase Cloud Messaging inválida
A chave do servidor do Firebase Cloud Messaging fornecida no dashboard da Braze é inválida. O sender ID fornecido deve corresponder ao referenciado no arquivo braze.xml do seu app. A chave do servidor e o sender ID são encontrados aqui no seu Firebase Console:
Cliques em push não estão sendo registrados
Se os cliques em push não estão sendo registrados, é possível que os dados de clique de push ainda não tenham sido enviados aos nossos servidores. O SDK Android da Braze pode limitar a frequência dos envios.
Se você implementou um tratamento de push personalizado, certifique-se de que está preservando a análise de dados nativa de push corretamente.
O registro de cliques em push é uma operação de rede e está sujeito às limitações de rede. Assim, embora o SDK Android da Braze tente acomodar falhas de rede e reenvie solicitações que falharam, alguma perda de eventos é esperada.
Deep links não estão funcionando
Verifique a configuração de deep links
Deep links podem ser testados com 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 push da Braze.
Verifique a lógica de tratamento personalizado
Se o deep link funciona corretamente com ADB mas não funciona a partir do push da Braze, verifique se algum tratamento personalizado de abertura de push foi implementado. Em caso afirmativo, verifique se o código de tratamento personalizado está processando corretamente o deep link recebido.
Desativar o comportamento de back stack
Se o deep link funciona corretamente com ADB mas não funciona a partir do push da Braze, tente desativar o back stack. Para isso, atualize seu arquivo braze.xml para incluir:
<bool name="com_braze_push_deep_link_back_stack_activity_enabled">false</bool>
Entendendo o fluxo de trabalho Braze/APNs
O serviço de Notificações por Push da Apple (APN) é a infraestrutura para enviar notificações por push a aplicativos em execução nas plataformas da Apple. Aqui está a estrutura simplificada de como as notificações por push são ativadas nos dispositivos dos seus usuários e como a Braze pode enviá-las:
- Você configura o certificado push e o perfil de provisionamento
- Os dispositivos se registram no APNs e fornecem à Braze os tokens por push
- Você lança uma Campaign de push na Braze
- A Braze remove os tokens inválidos
Etapa 1: Configurando o certificado de push e o perfil de provisionamento
Para desenvolver seu app, crie um certificado SSL para ativar as notificações por push. Esse certificado é incluído no perfil de provisionamento com o qual seu app é compilado e também deve ser carregado no 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, verifique se o certificado carregado no dashboard corresponde ao perfil de provisionamento que você está utilizando no momento.
Não altere o ambiente do certificado de push (desenvolvimento versus produção). Alterar o certificado de push para o ambiente errado pode fazer com que os tokens por push dos seus usuários sejam removidos acidentalmente, tornando-os inacessíveis por push.
Etapa 2: Os dispositivos se registram no APNs e fornecem tokens por push à Braze
Quando os usuários abrem seu app, 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 utilizam 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, em seu perfil de usuário na guia Engagement, e se torna elegível para receber notificações por push de Campaigns da Braze.
A partir do macOS 13, em determinados dispositivos, você pode testar notificações por push em um Simulador iOS 16 rodando no Xcode 14. Para mais detalhes, consulte as Notas de versão do Xcode 14.
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 imediata, e o token ainda aparece como válido até que o APNs o retire.
- Em algum momento, o APNs retira os 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, registra uma entrega bem-sucedida no perfil do usuário, embora o usuário possa não ter recebido a mensagem de fato por motivos como:
- O dispositivo está desligado.
- O dispositivo não está conectado à internet (Wi-Fi ou dados móveis).
- O usuário desinstalou o app recentemente.
A Braze utiliza o certificado SSL de push carregado no dashboard para autenticar e verificar se está autorizada a enviar notificações por push aos tokens por push fornecidos. Se o dispositivo estiver online, a notificação deve ser recebida pouco depois do envio da Campaign. 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 qualquer um 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.
É normal que o APNs inicialmente retorne um status de sucesso mesmo que um token se torne não registrado, pois o APNs não reporta imediatamente eventos de invalidação de token. O APNs atrasa intencionalmente o retorno de um status 410 para tokens inválidos em um cronograma aleatório, projetado para proteger a privacidade dos usuários e evitar o rastreamento de desinstalações de apps. Você pode continuar enviando notificações com segurança para um token não registrado até que o APNs retorne um status 410.
Analisando erros de push
O Observabilidade de mensagens mostra por que um push de uma Campaign ou Canvas não foi enviado, incluindo erros retornados pelo APNs ou FCM.
Erros comuns 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 informações 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.
Erros de notificação por push
Received unregistered sending to push token
- Verifique se o token por push enviado para a Braze pelo método
AppDelegate.braze?.notifications.register(deviceToken:)é válido. Analise o erro da Campaign ou Canvas em Observabilidade de mensagens. O token deve se parecer com algo como6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6, uma string longa contendo uma mistura de letras e números. Se o seu token por push parecer diferente, verifique o código para envio de tokens por push à Braze. - Verifique se o perfil de provisionamento de push corresponde ao ambiente que você está testando. Certificados universais podem ser configurados no dashboard da Braze para enviar ao ambiente 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 carregado na 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 (HTTP status 400) quando o token por push não corresponde ao topic (bundle ID) configurado para suas credenciais. Analise o erro da Campaign ou Canvas em Observabilidade de mensagens.
Para resolver a incompatibilidade:
- Confirme se o bundle ID do app corresponde ao App Bundle ID na Braze (Settings > App Settings > Push Notification Settings).
- Verifique se o perfil de provisionamento usado para compilar o app inclui a capacidade de push para esse bundle ID.
- Confirme se a credencial de push carregada na Braze corresponde ao ambiente do app (desenvolvimento versus produção).
- Para chaves
.p8, verifique se o Team ID e o Key ID na Braze correspondem à sua conta Apple Developer. - Carregue novamente uma chave
.p8válida ou um certificado.p12se 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. Existem 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 no registro de push
Nenhum prompt de registro de push
Se o aplicativo não solicita o registro de 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 o 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)
Verifique se seu app está configurado corretamente para permitir notificações por push. Pontos comuns de falha a serem verificados incluem:
- Verifique se o 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 momento. Se 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 você está baixando todos os perfis de provisionamento disponíveis da sua conta Apple Developer. Para confirmar, siga estas etapas:
- No Xcode, acesse Preferences > Accounts (ou use o atalho Command+,).
- Selecione o Apple ID que você usa para sua conta de desenvolvedor e clique em View Details.
- Na próxima página, clique em Refresh e confirme que você está baixando todos os perfis de provisionamento disponíveis.
- Verifique se você ativou corretamente a capacidade de push no seu app.
- Verifique se o perfil de provisionamento de push corresponde ao ambiente no qual você está testando. Certificados universais podem ser configurados no dashboard da Braze para enviar ao ambiente 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
registerPushTokendefinindo um breakpoint no seu código. - Certifique-se de que está testando com um dispositivo (push não funciona em um simulador) e que possui boa conectividade de rede.
Notificações por push enviadas mas não exibidas nos dispositivos dos usuários
Usuários “push registered” não estão mais ativados 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 de push que você carregou no dashboard não é o mesmo do perfil de provisionamento com o qual seu app foi compilado, o APNs rejeitará o token. Verifique se você carregou o certificado correto e concluiu outra sessão no app antes de tentar outra notificação de teste.
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 simultaneamente. Existem muitas “peças 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 caso você precise continuar a solução de problemas.
Mensagens não entregues a usuários “push registered”
App está em primeiro plano
Nas versões do iOS que não integram push por meio do framework UserNotifications, se o app estiver em primeiro plano quando a mensagem de push for recebida, ela não será exibida. Coloque o app em segundo plano nos seus dispositivos de teste antes de enviar mensagens de teste.
Notificação de teste agendada incorretamente
Verifique o agendamento que você definiu para a mensagem de teste. Se estiver configurado para entrega por fuso local ou Intelligent Timing, pode ser que você simplesmente ainda não tenha recebido a mensagem (ou estava com o app em primeiro plano quando ela foi recebida).
Usuário não está “push registered” para o app sendo testado
Verifique o perfil de usuário para o qual 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, portanto isso pode ser um falso positivo.
O seguinte indica um problema com o registro de push ou que o token do usuário foi retornado à Braze como inválido pelo APNs após um envio:
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 frameworkUserNotifications, a Braze não processará notificações por push quando o estado do aplicativo forUIApplicationStateActive. 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.
Deep links não funcionam
Para uma solução de problemas abrangente em todos os canais, incluindo links universais, esquemas personalizados, e-mail e provedores de terceiros como Branch, consulte Solução de problemas de deep linking.
Links web a partir de cliques em push não abrem
Links em notificações por push precisam ser compatíveis com ATS para serem abertos em web views. Certifique-se de que seus links web usam HTTPS. Para saber mais, consulte Conformidade com ATS.
Deep links a partir de cliques em push não abrem
A maior parte do código que lida com deep links também lida com a abertura de push. Primeiro, verifique se as aberturas de push estão sendo registradas. Se não, corrija esse problema (pois a correção geralmente resolve também o tratamento de links).
Se as aberturas estão sendo registradas, verifique se o problema é com o deep link em geral ou com o tratamento de deep links ao clicar em push. Para isso, teste se um deep link a partir de um clique em uma mensagem no app funciona.
Tocar em imagens de Push Story não faz nada
Se tocar em uma imagem de Push Story não faz nada, abra o Info.plist da Notification Content Extension e confirme que UNNotificationExtensionUserInteractionEnabled está como YES. O módulo BrazePushStory do SDK Swift precisa dessa chave para que a extensão possa receber toques. Consulte Push Stories.
Entendendo o fluxo de trabalho de push da Braze
O Firebase Cloud Messaging (FCM) é a infraestrutura do Google para notificações por push enviadas a aplicativos Android. Aqui está 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 Android da Braze o seu ID de remetente do Firebase. Além disso, será necessário fornecer uma chave de API para aplicativos de servidor ao dashboard da Braze. A Braze usará essa chave de API para enviar mensagens aos seus dispositivos. Você também precisará verificar se o serviço FCM está ativado no console do Google Developer.
Um erro comum durante esta etapa é usar a chave de API do identificador do app em vez da chave da API REST.
Etapa 2: Os dispositivos se registram no FCM e fornecem tokens por push à Braze
Em integrações típicas, o SDK Android da Braze cuidará do registro dos dispositivos para a funcionalidade FCM. Isso geralmente acontece imediatamente ao abrir o app pela primeira vez. Após o registro, a Braze receberá um ID de registro do FCM, que é usado para enviar mensagens especificamente para aquele dispositivo. Armazenaremos o ID de registro desse usuário, e ele passará a ter o status de “push registrado” caso não possuísse anteriormente um token por push para nenhum dos seus apps.
Etapa 3: Lance uma Campaign de push na Braze
Quando uma Campaign de push é lançada, a Braze faz solicitações ao FCM para entregar sua mensagem. A Braze usa a chave de API copiada no dashboard para autenticar e verificar que é possível enviar notificações por push para os tokens por push fornecidos.
Etapa 4: Remova tokens inválidos
Se o FCM 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. Se os usuários não tiverem outros tokens por push, eles não aparecerão mais como “Push Registered” na página de Segments.
Para mais detalhes sobre o FCM, visite Cloud messaging.
Revise os erros de push
Os erros de notificações por push de uma Campaign ou Canvas aparecem em Observabilidade de envio de mensagens.
Solução de problemas
Push não está sendo enviado
Suas mensagens de push podem não estar sendo enviadas devido às seguintes situações:
- Suas credenciais existem no projeto do Google Cloud Platform errado (sender ID incorreto).
- Suas credenciais têm o escopo de permissão errado.
- Você fez upload de credenciais erradas para o espaço de trabalho errado da Braze (sender ID incorreto).
Para outros problemas que podem impedir o envio de uma mensagem de push, consulte Guia do Usuário: Solução de problemas de notificações por push.
Nenhum usuário “push registered” aparecendo no dashboard da Braze (antes de enviar mensagens)
Confirme se o seu app está configurado corretamente para permitir notificações por push. Pontos de falha comuns a serem verificados incluem:
Sender ID incorreto
Verifique se o sender ID correto do FCM está incluído no arquivo braze.xml. Um sender ID incorreto leva a erros MismatchSenderID. Revise-os em Observabilidade de mensagens.
Registro na Braze não está ocorrendo
Como o registro do FCM é feito fora da Braze, a falha no registro pode ocorrer apenas em dois lugares:
- Durante o registro com o FCM
- Ao passar o token de push gerado pelo FCM para a Braze
Recomendamos definir um breakpoint ou registrar logs para confirmar que o token de push gerado pelo FCM está sendo enviado para a Braze. Se um token não for gerado corretamente ou não for gerado, recomendamos consultar a documentação do FCM.
Google Play Services não 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 de push não ocorrerá.
O Google Play Services não é instalado em emuladores Android sem as APIs do Google instaladas.
Dispositivo não conectado à internet
Verifique se seu dispositivo tem boa conectividade com a internet e não está enviando tráfego de rede por meio de um proxy.
Tocar na 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 com o valor padrão false, você precisará usar um Braze Push Callback para escutar e tratar os intents de push recebido e aberto.
Notificações por push com bounce
Se uma notificação por push não foi entregue, verifique se ela não sofreu bounce consultando o console de desenvolvedor. A seguir estão 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 sender ID do Firebase e a chave de API do FCM estão corretos.
Erro: InvalidRegistration
InvalidRegistration pode ser causado por um token de push malformado.
- Certifique-se de passar um token de push válido para a Braze a partir do Firebase Cloud Messaging.
Erro: NotRegistered
NotRegisteredtambém pode ocorrer quando múltiplos registros acontecem e um segundo registro invalida o primeiro token.
Notificações por push enviadas, mas não exibidas nos dispositivos dos usuários
Existem algumas razões pelas quais isso pode estar ocorrendo:
O app foi encerrado forçadamente
Se você encerrar forçadamente o app pelas configurações do sistema, suas notificações por push não serão enviadas. Abrir o app novamente reativará a capacidade do dispositivo de receber notificações por push.
BrazeFirebaseMessagingService não registrado
O BrazeFirebaseMessagingService deve ser devidamente registrado no AndroidManifest.xml para que as notificações por push apareçam:
<service android:name="com.braze.push.BrazeFirebaseMessagingService"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
Firewall está bloqueando o push
Se você está testando push por Wi-Fi, seu firewall pode estar bloqueando as portas necessárias para o FCM receber mensagens. Confirme que 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 IP listados no ASN do Google de 15169.
Fábrica de notificações personalizada retornando null
Se você implementou uma fábrica de notificações personalizada, certifique-se de que ela não está retornando null. Isso fará com que as notificações não sejam exibidas.
Usuários “push registered” não estão mais ativados após o envio de mensagens
Existem algumas razões pelas quais isso pode estar acontecendo:
O app foi desinstalado
Os usuários desinstalaram o app. Isso invalidará o token de push do FCM deles.
Chave do servidor do Firebase Cloud Messaging inválida
A chave do servidor do Firebase Cloud Messaging fornecida no dashboard da Braze é inválida. O sender ID fornecido deve corresponder ao referenciado no arquivo braze.xml do seu app. A chave do servidor e o sender ID são encontrados aqui no seu Firebase Console:
Cliques em push não estão sendo registrados
Se os cliques em push não estão sendo registrados, é possível que os dados de clique de push ainda não tenham sido enviados aos nossos servidores. O SDK Android da Braze pode limitar a frequência dos envios.
Se você implementou um tratamento de push personalizado, certifique-se de que está preservando a análise de dados nativa de push corretamente.
O registro de cliques em push é uma operação de rede e está sujeito às limitações de rede. Assim, embora o SDK Android da Braze tente acomodar falhas de rede e reenvie solicitações que falharam, alguma perda de eventos é esperada.
Deep links não estão funcionando
Verifique a configuração de deep links
Deep links podem ser testados com 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 push da Braze.
Verifique a lógica de tratamento personalizado
Se o deep link funciona corretamente com ADB mas não funciona a partir do push da Braze, verifique se algum tratamento personalizado de abertura de push foi implementado. Em caso afirmativo, verifique se o código de tratamento personalizado está processando corretamente o deep link recebido.
Desativar o comportamento de back stack
Se o deep link funciona corretamente com ADB mas não funciona a partir do push da Braze, tente desativar o back stack. Para isso, atualize seu arquivo braze.xml para incluir:
<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, o comportamento de tocar em uma notificação por push trazer automaticamente o app para o primeiro plano e abrir o deep link é controlado pela flag nativa com_braze_handle_push_deep_links_automatically, cujo valor padrão é false.
Com o padrão false:
- O SDK nativo ainda envia um broadcast
BRAZE_PUSH_CLICKEDe o listenerpush_openeddo 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:
<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 os apps de receberem push após o processo ser encerrado. Se você executar seu app no modo Release, deve ver push mesmo após o app ser fechado pelo alternador de tarefas.
Fábrica de notificações personalizada não está sendo definida corretamente
Fábricas de notificações personalizadas (e todos os delegates) devem estender Java.Lang.Object para funcionar corretamente na integração entre C# e Java. Consulte a documentação do Xamarin sobre 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.